# Format-token fields

Source: https://libtmux.org/en/rs/latest/topics/format-tokens/

> The typed fields every object exposes, mirroring tmux's own format tokens, and why a field is sometimes absent.

Object fields expose values from tmux's
[FORMATS](https://man.openbsd.org/tmux.1#FORMATS), such as [`pane_id`](<https://libtmux.org/en/rs/latest/mcp/reference/mcp-caller-calleridentity-pane_id/>),
[`window_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/window_zoomed_flag/), and [`session_name`](<https://libtmux.org/en/rs/latest/workspace/reference/config-workspace-session_name/>). The available fields depend on the
accessor, object scope, tmux version, and data requested by the read.

A token needs the right **scope** and **tmux version**. For example, a pane
token needs a pane context, and a token added after your tmux release may be
absent. Check the accessor's result before using a field that can be missing, as
described below.

<a id="the-absence-idiom-per-port"></a>

## Handling an absent field

Some handle accessors return `Option<T>` for unavailable values.
Check the reference for the selected accessor and its return type.

These examples read optional fields, including [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/) on tmux 3.3 or
newer:

[`crates/libtmux/src/formats.rs`](<https://github.com/libtmux/libtmux-rs/blob/84de9258a07d10bdd5f6da01b016a9ae06fe1210/crates/libtmux/src/formats.rs>) marks this token as optional. Consult the
reference for the accessor name.

<a id="a-generated-table-under-the-accessor"></a>

## Field availability

Field accessors retain the scope and version requirements of tmux tokens.

[`crates/libtmux/src/formats.rs`](<https://github.com/libtmux/libtmux-rs/blob/84de9258a07d10bdd5f6da01b016a9ae06fe1210/crates/libtmux/src/formats.rs>) records each token's tmux name, required
context, first supported release, decoder, and handling of empty values.
[`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/) requires pane context and tmux 3.3. Its text value
preserves arbitrary non-NUL bytes.

Version gates describe tmux behavior: [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/)
and [`pane_dead_time`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_time/) arrived in tmux 3.3, and a cluster of pane-geometry and
floating-pane tokens ([`pane_floating_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_floating_flag/), [`pane_pb_progress`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_pb_progress/), [`pane_x`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_x/),
[`pane_y`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_y/), [`pane_z`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_z/), [`pane_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_zoomed_flag/), [`bracket_paste_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/bracket_paste_flag/),
[`synchronized_output_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/synchronized_output_flag/), among others) arrived together in 3.7.

## Fields promoted from the active child

tmux's format engine includes active-child fields when listing a parent. A
[`list-sessions -F`](https://libtmux.org/en/tmux/latest/manual/list-sessions/) row can include [`window_id`](<https://libtmux.org/en/rs/latest/reference/pane-pane-window_id/>) and [`pane_id`](<https://libtmux.org/en/rs/latest/mcp/reference/mcp-caller-calleridentity-pane_id/>) for the active
window and pane. Check the port reference for typed access to those fields, or
use the explicit relationships described in [Traversal](https://libtmux.org/en/rs/latest/topics/traversal/).

A pane context can include parent window and session fields. A session cannot
identify one attached client when several clients may be attached, so client
tokens such as [`client_name`](https://libtmux.org/en/tmux/latest/catalog/formats/client_name/) require a client context.