# Key Format Options (XTFMTKEYS, XTQFMTKEYS)

> Choose whether keys with modifiers are sent as CSI 27 ; m ; code ~ or as CSI code ; m u, and ask which is chosen.

- **Sequence:** `CSI > Pp ; Pv f`
- **XTQFMTKEYS**, Query Key Format Options: `CSI > Pm g`
- **xterm:** [Functions using CSI](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)

[XTMODKEYS](https://control-codes.page/csi/xtmodkeys/index.html.md) says *whether* xterm sends a key with its
modifiers as an escape sequence; these say *how*. Each of xterm's
`modify…Keys` resources has a `format…Keys` companion, and for the keys
`modifyOtherKeys` covers, `formatOtherKeys` chooses between two forms of
Control and `,`:

| `formatOtherKeys` | Sends |
| --- | --- |
| `0`, the default | `CSI 27 ; 5 ; 44 ~`, function key 27 with the modifiers and the character |
| `1` | `CSI 44 ; 5 u`, the character with the modifiers |

The second is the form proposed by [fixterms](https://control-codes.page/proposals/fixterms/index.html.md), and
xterm added `formatOtherKeys` at its author's request, in
[patch 235](https://invisible-island.net/xterm/xterm.log.html#xterm_235)
(2008), as a resource only
([`modifyOtherKey`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/input.c#L759-L782)).
[Patch 398](https://invisible-island.net/xterm/xterm.log.html#xterm_398)
(2025) gave the other key categories a format resource each and added these
sequences to set and ask for them, so a program can now ask for the `CSI u`
form itself, with `CSI > 4 ; 1 f` alongside `CSI > 4 ; 2 m`.

`Pp` picks the resource, numbered as for XTMODKEYS:

| `Pp` | Resource | Default |
| --- | --- | --- |
| `0` | `formatKeyboard` | `0` |
| `1` | `formatCursorKeys` | `0` |
| `2` | `formatFunctionKeys` | `0` |
| `3` | `formatKeypadKeys` | `0` |
| `4` | `formatOtherKeys` | `0` |
| `6` | `formatModifierKeys` | `0` |
| `7` | `formatSpecialKeys` | `0` |

`5` is reserved, as it is for XTMODKEYS. `formatKeyboard` has no resource
to set it from, so it starts at `0` and only these sequences change it. The
others take effect only where their `modify…Keys` resource is high enough to
send an escape sequence at all.

The forms, in a default xterm
([`CASE_SET_FMT_KEYS`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/charproc.c#L6320-L6341),
[`set_fmt_fkeys`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/charproc.c#L2426-L2465),
[`report_fmt_fkeys`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/charproc.c#L2509-L2549)):

- `CSI > Pp ; Pv f` sets one to `Pv`, which is not checked. `CSI > Pp f`,
  with no value, puts it back as it started. `CSI > f` changes nothing:
  the code has a branch that would put back `1` to `5` when there are no
  parameters, but xterm counts an empty list as one parameter with its
  default, `-1`, so the branch is never taken and resource `-1` is set,
  which there is none of.
- `CSI > Pp g` asks, and is answered as `CSI > Pp ; Pv f`, a sequence that
  would set it back; several at once, `CSI > 1 ; 4 g`, get an answer each.
  A resource xterm does not have is answered with `65535`, the `-1` it
  stands for read as sixteen unsigned bits, and so `CSI > g`, which asks
  about resource `-1`, is answered `CSI > 65535 ; 65535 f`.
- [DECRQSS](https://control-codes.page/dcs/decrqss/index.html.md) asks as well, as `DCS $ q > Pp f ST`, but the
  answer ends in `m`, as XTQMODKEYS's does: `DCS 1 $ r > Pp ; Pv m ST`
  ([`misc.c`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/misc.c#L5028-L5061)).
  Sent back, that would set the XTMODKEYS resource of the same number.
- [DECSTR](https://control-codes.page/csi/decstr/index.html.md) and [RIS](https://control-codes.page/esc/ris/index.html.md) put them all back as they
  started
  ([`ReallyReset`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/charproc.c#L14421)).

xterm's own *Control Sequences* documents the query as `CSI ? Pp g`
([`ctlseqs.ms`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/ctlseqs.ms#L1463-L1492)),
but its parser has the query only in the `CSI >` table, beside the set
([`dec2_table`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/VTPrsTbl.c#L4826-L4830));
in the `CSI ?` table `g` goes to the ground state
([`dec_table`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/VTPrsTbl.c#L4176-L4180)).
So `CSI ? 4 g` is not answered, and `CSI > 4 g` is.

libghostty-vt ignores all of it: it reads the `>` and `?` as intermediates
and ignores `f` and `g` with any, so neither moves the cursor as HVP or
clears a tab stop as TBC would. Its key encoder never sends the `CSI u`
form for `modifyOtherKeys`. The cases follow a default xterm, so those that
ask are known differences.

None of the other terminals this site runs has it, and two of them misread
it. kitty 0.49.1 takes `CSI > 2 ; 5 f` for HVP and moves the cursor
(XTFMTKEYS-10). pyte does the same, takes `CSI > g` for TBC and clears a
tab stop (XTFMTKEYS-11), and raises an exception on `CSI ? 4 g`, which it
hands to its tab-clearing method with a `private` argument the method does
not take (XTFMTKEYS-9).

## Support

| Terminal | Version | Support | Notes |
| --- | --- | --- | --- |
| VT220 | [manual](https://vt100.net/docs/vt220-rm/), 2nd ed., 1984 | No | not in the manual |
| VT510 | [manual](https://vt100.net/docs/vt510-rm/), 1st ed., 1993 | No | not in the manual |
| xterm | patch 412, [xterm-411a](https://github.com/ThomasDickey/xterm-snapshots/tree/xterm-411a) | Yes |  |
| libghostty-vt | [919dca5](https://github.com/ghostty-org/ghostty/tree/919dca5c848d43a489a4cb2e1feade016f0fa2db) | No | ignores both (XTFMTKEYS-1 to XTFMTKEYS-8, XTFMTKEYS-12) |
| kitty | 0.49.1, [run in a VM](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/kitty.json) | No | fails the 2 cases that show it working |
| foot | 1.28.0, [run in a VM](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/foot.json) | No | fails the 2 cases that show it working |
| pyte | 0.8.2, [run as a library](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/pyte.json) | No | fails the 2 cases that show it working |
| xterm.js headless | 6.0.0, [run as a library](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/xtermjs.json) | No | fails the 2 cases that show it working |
| alacritty_terminal | 0.26.0, [run as a library](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/alacritty.json) | No | fails the 2 cases that show it working |
| ConEmu | build 230724, its [documentation](https://conemu.github.io/en/AnsiEscapeCodes.html) | No | not in ConEmu's list; [ANSI escape codes](https://conemu.github.io/en/AnsiEscapeCodes.html) |
| rxvt-unicode | 9.31, [run in a VM](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/urxvt.json) | No | fails the 2 cases that show it working |
| VTE | 0.84.1, [run as a library](https://git.jcollie.dev/jeff/control-codes/src/branch/main/emulators/results/vte.json) | No | fails the 2 cases that show it working |

## Validation

### XTFMTKEYS-1: The defaults

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>0;1;2;3;4;6;7g
```

Expected screen:

```text
|______|
reply \e[>0;0f\e[>1;0f\e[>2;0f\e[>3;0f\e[>4;0f\e[>6;0f\e[>7;0f
```

### XTFMTKEYS-2: The fixterms form for modifyOtherKeys

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>4;1f
\e[>4g
```

Expected screen:

```text
|______|
reply \e[>4;1f
```

### XTFMTKEYS-3: Put it back

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>4;1f
\e[>4f
\e[>4g
```

Expected screen:

```text
|______|
reply \e[>4;0f
```

### XTFMTKEYS-4: Without a resource, nothing changes

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>1;1f
\e[>4;1f
\e[>6;1f
\e[>f
\e[>1;4;6g
```

Expected screen:

```text
|______|
reply \e[>1;1f\e[>4;1f\e[>6;1f
```

### XTFMTKEYS-5: The value is not checked

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>4;9f
\e[>4g
```

Expected screen:

```text
|______|
reply \e[>4;9f
```

### XTFMTKEYS-6: A resource xterm does not have

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>8g
```

Expected screen:

```text
|______|
reply \e[>8;65535f
```

### XTFMTKEYS-7: DECSTR puts them back

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>4;1f
\e[!p
\e[>4g
```

Expected screen:

```text
|______|
reply \e[>4;0f
```

### XTFMTKEYS-8: Through DECRQSS, ending in m

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>4;1f
\eP$q>4f\e\\
```

Expected screen:

```text
|______|
reply \eP1$r>4;1m\e\\
```

### XTFMTKEYS-9: The documented query is not answered

Input, one step per line:

```text
\e[?4g
```

Expected screen:

```text
|______|
reply none
```

### XTFMTKEYS-10: Not HVP

Input, one step per line:

```text
A
\e[>2;5f
B
```

Expected screen:

```text
|AB______|
|________|
cursor 1,3
```

### XTFMTKEYS-11: Not TBC

Input, one step per line:

```text
\t        # to the stop at column 9
\e[>g     # what TBC would read as clearing it
\r\t
X
```

Expected screen:

```text
|________X___________|
```

### XTFMTKEYS-12: A query with nothing to ask

*A known difference: libghostty-vt does not pass this case.*

Input, one step per line:

```text
\e[>g
```

Expected screen:

```text
|______|
reply \e[>65535;65535f
```

---

This is the Markdown version of <https://control-codes.page/csi/xtfmtkeys/>. On that page every validation case runs live in libghostty-vt, the terminal emulation core of Ghostty, compiled to WebAssembly.

The validation cases are written in the notation described in <https://control-codes.page/notation/index.html.md>.
