Color Scheme Reports

Encode the reply to a color scheme query (CSI ? 996 n). More...

Detailed Description

Encode the reply to a color scheme query (CSI ? 996 n).

A color scheme report tells a program whether your terminal is light or dark.

You need this when a program sets mode 2031 and expects to hear when the scheme changes. Encode the report and write it to the pty yourself. You don't need it to answer a CSI ? 996 n query. A terminal does that for you through a GhosttyTerminalColorSchemeFn.

Example

int main() {
  uint8_t buf[16];
  size_t written = 0;
 
  GhosttyResult result = ghostty_color_scheme_report_encode(
      GHOSTTY_COLOR_SCHEME_DARK, buf, sizeof(buf), &written);
 
  if (result == GHOSTTY_SUCCESS) {
    printf("Encoded %zu bytes: ", written);
    fwrite(buf, 1, written, stdout);
    printf("\n");
  }
 
  return 0;
}

Full program: c-vt-color-scheme/src/main.c

See Light and dark reports for when to send one.

Functions
GHOSTTY_API GhosttyResult	ghostty_color_scheme_report_encode (GhosttyColorScheme scheme, uint8_t *buf, size_t buf_len, size_t *out_written)

Function Documentation

ghostty_color_scheme_report_encode()

GHOSTTY_API GhosttyResult ghostty_color_scheme_report_encode	(	GhosttyColorScheme	scheme,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Encode a color scheme report into an escape sequence.

Encodes a color scheme report into the provided buffer. Dark color schemes emit ESC [ ? 997 ; 1 n, and light color schemes emit ESC [ ? 997 ; 2 n. The encoded bytes are identical to the terminal's internal CSI ? 996 n query response.

Hosts should gate unsolicited sends on GHOSTTY_MODE_COLOR_SCHEME_REPORT (mode 2031) being set. Read it with ghostty_terminal_get() and GHOSTTY_TERMINAL_DATA_MODE.

If buf is too small, this returns GHOSTTY_OUT_OF_SPACE and sets out_written to the size needed. The buffer may then hold part of the sequence, which you should discard. To get the size without encoding anything, pass NULL for buf and 0 for buf_len.

Parameters

	scheme	The color scheme to encode
	buf	Buffer to write the sequence into. May be NULL if buf_len is 0.
	buf_len	Size of buf in bytes
[out]	out_written	The number of bytes written, or the size needed if the result is GHOSTTY_OUT_OF_SPACE

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer is too small

Examples

c-vt-color-scheme/src/main.c.