Detailed Description

Complete terminal emulator state and rendering.

A terminal instance manages the full emulator state including the screen, scrollback, cursor, styles, modes, and VT stream processing.

Once a terminal session is up and running, you can configure a key encoder to write keyboard input via ghostty_key_encoder_setopt_from_terminal().

Example: VT stream processing

  // Create a terminal
  GhosttyTerminal terminal;
  GhosttyTerminalOptions opts = {
    .cols = 80,
    .rows = 24,
    .max_scrollback = 0,
  };
  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
  assert(result == GHOSTTY_SUCCESS);

  // Feed VT data into the terminal
  const char *text = "Hello, World!\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
 
  // ANSI color codes: ESC[1;32m = bold green, ESC[0m = reset
  text = "\x1b[1;32mGreen Text\x1b[0m\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
 
  // Cursor positioning: ESC[1;1H = move to row 1, column 1
  text = "\x1b[1;1HTop-left corner\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
 
  // Cursor movement: ESC[5B = move down 5 lines
  text = "\x1b[5B";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
  text = "Moved down!\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
 
  // Erase line: ESC[2K = clear entire line
  text = "\x1b[2K";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
  text = "New content\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
 
  // Multiple lines
  text = "Line A\r\nLine B\r\nLine C\r\n";
  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));

Effects

By default, the terminal sequence processing with ghostty_terminal_vt_write() only process sequences that directly affect terminal state and ignores sequences that have side effect behavior or require responses. These sequences include things like bell characters, title changes, device attributes queries, and more. To handle these sequences, the embedder must configure "effects."

Effects are callbacks that the terminal invokes in response to VT sequences processed during ghostty_terminal_vt_write(). They let the embedding application react to terminal-initiated events such as bell characters, title changes, device status report responses, and more.

Each effect is registered with ghostty_terminal_set() using the corresponding GhosttyTerminalOption identifier. A NULL value pointer clears the callback and disables the effect.

A userdata pointer can be attached via GHOSTTY_TERMINAL_OPT_USERDATA and is passed to every callback, allowing callers to route events back to their own application state without global variables. You cannot specify different userdata for different callbacks.

All callbacks are invoked synchronously during ghostty_terminal_vt_write(). Callbacks must not call ghostty_terminal_vt_write() on the same terminal (no reentrancy). And callbacks must be very careful to not block for too long or perform expensive operations, since they are blocking further IO processing.

The available effects are:

Option	Callback Type	Trigger
GHOSTTY_TERMINAL_OPT_WRITE_PTY	GhosttyTerminalWritePtyFn	Query responses written back to the pty
GHOSTTY_TERMINAL_OPT_BELL	GhosttyTerminalBellFn	BEL character (0x07)
GHOSTTY_TERMINAL_OPT_TITLE_CHANGED	GhosttyTerminalTitleChangedFn	Title change via OSC 0 / OSC 2
GHOSTTY_TERMINAL_OPT_ENQUIRY	GhosttyTerminalEnquiryFn	ENQ character (0x05)
GHOSTTY_TERMINAL_OPT_XTVERSION	GhosttyTerminalXtversionFn	XTVERSION query (CSI > q)
GHOSTTY_TERMINAL_OPT_SIZE	GhosttyTerminalSizeFn	XTWINOPS size query (CSI 14/16/18 t)
GHOSTTY_TERMINAL_OPT_COLOR_SCHEME	GhosttyTerminalColorSchemeFn	Color scheme query (CSI ? 996 n)
GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES	GhosttyTerminalDeviceAttributesFn	Device attributes query (CSI c / > c / = c)

Defining a write_pty callback

void on_write_pty(GhosttyTerminal terminal,
                  void* userdata,
                  const uint8_t* data,
                  size_t len) {
  (void)terminal;
  (void)userdata;
  printf("  write_pty (%zu bytes): ", len);
  fwrite(data, 1, len, stdout);
  printf("\n");
}

Defining a bell callback

void on_bell(GhosttyTerminal terminal, void* userdata) {
  (void)terminal;
  int* count = (int*)userdata;
  (*count)++;
  printf("  bell! (count=%d)\n", *count);
}

Defining a title_changed callback

void on_title_changed(GhosttyTerminal terminal, void* userdata) {
  (void)userdata;
  // Query the cursor position to confirm the terminal processed the
  // title change (the title itself is tracked by the embedder via the
  // OSC parser or its own state).
  uint16_t col = 0;
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_CURSOR_X, &col);
  printf("  title changed (cursor at col %u)\n", col);
}

Registering effects and processing VT data

int main() {
  // Create a terminal
  GhosttyTerminal terminal = NULL;
  GhosttyTerminalOptions opts = {
    .cols = 80,
    .rows = 24,
    .max_scrollback = 0,
  };
  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create terminal\n");
    return 1;
  }
 
  // Set up userdata — a simple bell counter
  int bell_count = 0;
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_USERDATA, &bell_count);
 
  // Register effect callbacks
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
      (const void *)on_write_pty);
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_BELL,
      (const void *)on_bell);
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_TITLE_CHANGED,
      (const void *)on_title_changed);
 
  // Feed VT data that triggers effects:
 
  // 1. Bell (BEL = 0x07)
  printf("Sending BEL:\n");
  const uint8_t bel = 0x07;
  ghostty_terminal_vt_write(terminal, &bel, 1);
 
  // 2. Title change (OSC 2 ; <title> ST)
  printf("Sending title change:\n");
  const char* title_seq = "\x1B]2;Hello Effects\x1B\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)title_seq,
                            strlen(title_seq));
 
  // 3. Device status report (DECRQM for wraparound mode ?7)
  //    triggers write_pty with the response
  printf("Sending DECRQM query:\n");
  const char* decrqm = "\x1B[?7$p";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)decrqm,
                            strlen(decrqm));
 
  // 4. Another bell to show the counter increments
  printf("Sending another BEL:\n");
  ghostty_terminal_vt_write(terminal, &bel, 1);
 
  printf("Total bells: %d\n", bell_count);
 
  ghostty_terminal_free(terminal);
  return 0;
}

Color Theme

The terminal maintains a set of colors used for rendering: a foreground color, a background color, a cursor color, and a 256-color palette. Each of these has two layers: a default value set by the embedder, and an override value that programs running in the terminal can set via OSC escape sequences (e.g. OSC 10/11/12 for foreground/background/cursor, OSC 4 for individual palette entries).

Default Colors

Use ghostty_terminal_set() with the color options to configure the default colors. These represent the theme or configuration chosen by the embedder. Passing NULL clears the default, leaving the color unset.

Option	Input Type	Description
GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND	GhosttyColorRgb*	Default foreground color
GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND	GhosttyColorRgb*	Default background color
GHOSTTY_TERMINAL_OPT_COLOR_CURSOR	GhosttyColorRgb*	Default cursor color
GHOSTTY_TERMINAL_OPT_COLOR_PALETTE	GhosttyColorRgb[256]*	Default 256-color palette

For the palette, passing NULL resets to the built-in default palette. The palette set operation preserves any per-index OSC overrides that programs have applied; only unmodified indices are updated.

Reading colors

Use ghostty_terminal_get() to read colors. There are two variants for each color: the effective value (which returns the OSC override if one is active, otherwise the default) and the default value (which ignores any OSC overrides).

Data	Output Type	Description
GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND	GhosttyColorRgb*	Effective foreground (override or default)
GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND	GhosttyColorRgb*	Effective background (override or default)
GHOSTTY_TERMINAL_DATA_COLOR_CURSOR	GhosttyColorRgb*	Effective cursor (override or default)
GHOSTTY_TERMINAL_DATA_COLOR_PALETTE	GhosttyColorRgb[256]*	Current palette (with any OSC overrides)
GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT	GhosttyColorRgb*	Default foreground only (ignores OSC override)
GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT	GhosttyColorRgb*	Default background only (ignores OSC override)
GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT	GhosttyColorRgb*	Default cursor only (ignores OSC override)
GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT	GhosttyColorRgb[256]*	Default palette only (ignores OSC overrides)

For foreground, background, and cursor colors, the getters return GHOSTTY_NO_VALUE if no color is configured (neither a default nor an OSC override). The palette getters always succeed since the palette always has a value (the built-in default if nothing else is set).

Setting a color theme

void set_color_theme(GhosttyTerminal terminal) {
  // Set default foreground (light gray) and background (dark)
  GhosttyColorRgb fg = { .r = 0xDD, .g = 0xDD, .b = 0xDD };
  GhosttyColorRgb bg = { .r = 0x1E, .g = 0x1E, .b = 0x2E };
  GhosttyColorRgb cursor = { .r = 0xF5, .g = 0xE0, .b = 0xDC };
 
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND, &fg);
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND, &bg);
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_CURSOR, &cursor);
 
  // Set a custom palette — start from the built-in default and override
  // the first 8 entries with a custom dark theme.
  GhosttyColorRgb palette[256];
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE, palette);
 
  palette[GHOSTTY_COLOR_NAMED_BLACK]   = (GhosttyColorRgb){ 0x45, 0x47, 0x5A };
  palette[GHOSTTY_COLOR_NAMED_RED]     = (GhosttyColorRgb){ 0xF3, 0x8B, 0xA8 };
  palette[GHOSTTY_COLOR_NAMED_GREEN]   = (GhosttyColorRgb){ 0xA6, 0xE3, 0xA1 };
  palette[GHOSTTY_COLOR_NAMED_YELLOW]  = (GhosttyColorRgb){ 0xF9, 0xE2, 0xAF };
  palette[GHOSTTY_COLOR_NAMED_BLUE]    = (GhosttyColorRgb){ 0x89, 0xB4, 0xFA };
  palette[GHOSTTY_COLOR_NAMED_MAGENTA] = (GhosttyColorRgb){ 0xF5, 0xC2, 0xE7 };
  palette[GHOSTTY_COLOR_NAMED_CYAN]    = (GhosttyColorRgb){ 0x94, 0xE2, 0xD5 };
  palette[GHOSTTY_COLOR_NAMED_WHITE]   = (GhosttyColorRgb){ 0xBA, 0xC2, 0xDE };
 
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_PALETTE, palette);
}

Reading effective and default colors

void print_color(GhosttyTerminal terminal,
                 const char* name,
                 GhosttyTerminalData effective_data,
                 GhosttyTerminalData default_data) {
  GhosttyColorRgb color;
 
  GhosttyResult res = ghostty_terminal_get(terminal, effective_data, &color);
  if (res == GHOSTTY_SUCCESS) {
    printf("  %-12s effective: #%02X%02X%02X", name, color.r, color.g, color.b);
  } else {
    printf("  %-12s effective: (not set)", name);
  }
 
  res = ghostty_terminal_get(terminal, default_data, &color);
  if (res == GHOSTTY_SUCCESS) {
    printf("  default: #%02X%02X%02X\n", color.r, color.g, color.b);
  } else {
    printf("  default: (not set)\n");
  }
}
 
void print_all_colors(GhosttyTerminal terminal, const char* label) {
  printf("%s:\n", label);
  print_color(terminal, "foreground",
      GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND,
      GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT);
  print_color(terminal, "background",
      GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND,
      GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT);
  print_color(terminal, "cursor",
      GHOSTTY_TERMINAL_DATA_COLOR_CURSOR,
      GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT);
 
  // Show palette index 0 (black) as an example
  GhosttyColorRgb palette[256];
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE, palette);
  printf("  %-12s effective: #%02X%02X%02X", "palette[0]",
      palette[0].r, palette[0].g, palette[0].b);
 
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT,
      palette);
  printf("  default: #%02X%02X%02X\n", palette[0].r, palette[0].g, palette[0].b);
}

Full example with OSC overrides

int main() {
  // Create a terminal
  GhosttyTerminal terminal = NULL;
  GhosttyTerminalOptions opts = {
    .cols = 80,
    .rows = 24,
    .max_scrollback = 0,
  };
  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create terminal\n");
    return 1;
  }
 
  // Before setting any colors, everything is unset
  print_all_colors(terminal, "Before setting defaults");
 
  // Set our color theme defaults
  set_color_theme(terminal);
  print_all_colors(terminal, "\nAfter setting defaults");
 
  // Simulate an OSC override (e.g. a program running inside the
  // terminal changes the foreground via OSC 10)
  const char* osc_fg = "\x1B]10;rgb:FF/00/00\x1B\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)osc_fg,
                            strlen(osc_fg));
  print_all_colors(terminal, "\nAfter OSC foreground override");
 
  // Clear the foreground default — the OSC override is still active
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND, NULL);
  print_all_colors(terminal, "\nAfter clearing foreground default");
 
  ghostty_terminal_free(terminal);
  return 0;
}

Typedefs
typedef void(*	GhosttyTerminalBellFn) (GhosttyTerminal terminal, void *userdata)
typedef bool(*	GhosttyTerminalColorSchemeFn) (GhosttyTerminal terminal, void userdata, GhosttyColorScheme out_scheme)
typedef bool(*	GhosttyTerminalDeviceAttributesFn) (GhosttyTerminal terminal, void userdata, GhosttyDeviceAttributes out_attrs)
typedef GhosttyString(*	GhosttyTerminalEnquiryFn) (GhosttyTerminal terminal, void *userdata)
typedef bool(*	GhosttyTerminalSizeFn) (GhosttyTerminal terminal, void userdata, GhosttySizeReportSize out_size)
typedef void(*	GhosttyTerminalTitleChangedFn) (GhosttyTerminal terminal, void *userdata)
typedef void(*	GhosttyTerminalWritePtyFn) (GhosttyTerminal terminal, void userdata, const uint8_t data, size_t len)
typedef GhosttyString(*	GhosttyTerminalXtversionFn) (GhosttyTerminal terminal, void *userdata)
typedef struct GhosttyTerminalImpl *	GhosttyTerminal

Enumerations
enum	GhosttyColorScheme
enum	GhosttyTerminalScrollViewportTag { GHOSTTY_SCROLL_VIEWPORT_TOP , GHOSTTY_SCROLL_VIEWPORT_BOTTOM , GHOSTTY_SCROLL_VIEWPORT_DELTA , GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyTerminalScreen { GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0 , GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1 , GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyTerminalOption { GHOSTTY_TERMINAL_OPT_USERDATA = 0 , GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1 , GHOSTTY_TERMINAL_OPT_BELL = 2 , GHOSTTY_TERMINAL_OPT_ENQUIRY = 3 , GHOSTTY_TERMINAL_OPT_XTVERSION = 4 , GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5 , GHOSTTY_TERMINAL_OPT_SIZE = 6 , GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7 , GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8 , GHOSTTY_TERMINAL_OPT_TITLE = 9 , GHOSTTY_TERMINAL_OPT_PWD = 10 , GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11 , GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12 , GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13 , GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14 , GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15 , GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16 , GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17 , GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18 , GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19 , GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20 , GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyTerminalData { GHOSTTY_TERMINAL_DATA_INVALID = 0 , GHOSTTY_TERMINAL_DATA_COLS = 1 , GHOSTTY_TERMINAL_DATA_ROWS = 2 , GHOSTTY_TERMINAL_DATA_CURSOR_X = 3 , GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4 , GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5 , GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6 , GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7 , GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8 , GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9 , GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10 , GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11 , GHOSTTY_TERMINAL_DATA_TITLE = 12 , GHOSTTY_TERMINAL_DATA_PWD = 13 , GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14 , GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15 , GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16 , GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17 , GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18 , GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19 , GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20 , GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21 , GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22 , GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23 , GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24 , GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25 , GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26 , GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27 , GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28 , GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29 , GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30 , GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_terminal_new (const GhosttyAllocator allocator, GhosttyTerminal terminal, GhosttyTerminalOptions options)
GHOSTTY_API void	ghostty_terminal_free (GhosttyTerminal terminal)
GHOSTTY_API void	ghostty_terminal_reset (GhosttyTerminal terminal)
GHOSTTY_API GhosttyResult	ghostty_terminal_resize (GhosttyTerminal terminal, uint16_t cols, uint16_t rows, uint32_t cell_width_px, uint32_t cell_height_px)
GHOSTTY_API GhosttyResult	ghostty_terminal_set (GhosttyTerminal terminal, GhosttyTerminalOption option, const void *value)
GHOSTTY_API void	ghostty_terminal_vt_write (GhosttyTerminal terminal, const uint8_t *data, size_t len)
GHOSTTY_API void	ghostty_terminal_scroll_viewport (GhosttyTerminal terminal, GhosttyTerminalScrollViewport behavior)
GHOSTTY_API GhosttyResult	ghostty_terminal_mode_get (GhosttyTerminal terminal, GhosttyMode mode, bool *out_value)
GHOSTTY_API GhosttyResult	ghostty_terminal_mode_set (GhosttyTerminal terminal, GhosttyMode mode, bool value)
GHOSTTY_API GhosttyResult	ghostty_terminal_get (GhosttyTerminal terminal, GhosttyTerminalData data, void *out)
GHOSTTY_API GhosttyResult	ghostty_terminal_get_multi (GhosttyTerminal terminal, size_t count, const GhosttyTerminalData keys, void values, size_t out_written)
GHOSTTY_API GhosttyResult	ghostty_terminal_grid_ref (GhosttyTerminal terminal, GhosttyPoint point, GhosttyGridRef *out_ref)
GHOSTTY_API GhosttyResult	ghostty_terminal_point_from_grid_ref (GhosttyTerminal terminal, const GhosttyGridRef ref, GhosttyPointTag tag, GhosttyPointCoordinate out)

Data Structures
struct	GhosttyDeviceAttributesPrimary
struct	GhosttyDeviceAttributesSecondary
struct	GhosttyDeviceAttributesTertiary
struct	GhosttyDeviceAttributes
struct	GhosttyTerminalOptions
union	GhosttyTerminalScrollViewportValue
struct	GhosttyTerminalScrollViewport
struct	GhosttyTerminalScrollbar

Typedef Documentation

◆ GhosttyTerminal

typedef struct GhosttyTerminalImpl* GhosttyTerminal

Opaque handle to a terminal instance.

Examples: c-vt-formatter/src/main.c, c-vt-grid-traverse/src/main.c, and c-vt-kitty-graphics/src/main.c.

Definition at line 95 of file types.h.

◆ GhosttyTerminalBellFn

typedef void(* GhosttyTerminalBellFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for bell.

Called when the terminal receives a BEL character (0x07).

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 262 of file terminal.h.

◆ GhosttyTerminalColorSchemeFn

typedef bool(* GhosttyTerminalColorSchemeFn) (GhosttyTerminal terminal, void *userdata, GhosttyColorScheme *out_scheme)

Callback function type for color scheme queries (CSI ? 996 n).

Called when the terminal receives a color scheme device status report query. Return true and fill *out_scheme with the current color scheme, or return false to silently ignore the query.

Parameters

	Terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_scheme	Pointer to store the current color scheme

Returns: true if the color scheme was filled, false to ignore the query

Definition at line 279 of file terminal.h.

◆ GhosttyTerminalDeviceAttributesFn

typedef bool(* GhosttyTerminalDeviceAttributesFn) (GhosttyTerminal terminal, void *userdata, GhosttyDeviceAttributes *out_attrs)

Callback function type for device attributes queries (DA1/DA2/DA3).

Called when the terminal receives a device attributes query (CSI c, CSI > c, or CSI = c). Return true and fill *out_attrs with the response data, or return false to silently ignore the query.

The terminal uses whichever sub-struct (primary, secondary, tertiary) matches the request type, but all three should be filled for simplicity.

Parameters

	Terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_attrs	Pointer to store the device attributes response

Returns: true if attributes were filled, false to ignore the query

Definition at line 300 of file terminal.h.

◆ GhosttyTerminalEnquiryFn

typedef GhosttyString(* GhosttyTerminalEnquiryFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for enquiry (ENQ, 0x05).

Called when the terminal receives an ENQ character. Return the response bytes as a GhosttyString. The memory must remain valid until the callback returns. Return a zero-length string to send no response.

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Returns: The response bytes to write back to the pty

Definition at line 318 of file terminal.h.

◆ GhosttyTerminalSizeFn

typedef bool(* GhosttyTerminalSizeFn) (GhosttyTerminal terminal, void *userdata, GhosttySizeReportSize *out_size)

Callback function type for size queries (XTWINOPS).

Called in response to XTWINOPS size queries (CSI 14/16/18 t). Return true and fill *out_size with the current terminal geometry, or return false to silently ignore the query.

Parameters

	Terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_size	Pointer to store the terminal size information

Returns: true if size was filled, false to ignore the query

Definition at line 335 of file terminal.h.

◆ GhosttyTerminalTitleChangedFn

typedef void(* GhosttyTerminalTitleChangedFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for title_changed.

Called when the terminal title changes via escape sequences (e.g. OSC 0 or OSC 2). The new title can be queried from the terminal after the callback returns.

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 351 of file terminal.h.

◆ GhosttyTerminalWritePtyFn

typedef void(* GhosttyTerminalWritePtyFn) (GhosttyTerminal terminal, void *userdata, const uint8_t *data, size_t len)

Callback function type for write_pty.

Called when the terminal needs to write data back to the pty, for example in response to a device status report or mode query. The data is only valid for the duration of the call; callers must copy it if it needs to persist.

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
data	Pointer to the response bytes
len	Length of the response in bytes

Definition at line 369 of file terminal.h.

◆ GhosttyTerminalXtversionFn

typedef GhosttyString(* GhosttyTerminalXtversionFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for XTVERSION.

Called when the terminal receives an XTVERSION query (CSI > q). Return the version string (e.g. "myterm 1.0") as a GhosttyString. The memory must remain valid until the callback returns. Return a zero-length string to report the default "libghostty" version.

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Returns: The version string to report

Definition at line 388 of file terminal.h.

Enumeration Type Documentation

◆ GhosttyColorScheme

enum GhosttyColorScheme

Color scheme reported in response to a CSI ? 996 n query.

Definition at line 74 of file device.h.

◆ GhosttyTerminalData

enum GhosttyTerminalData

Terminal data types.

These values specify what type of data to extract from a terminal using ghostty_terminal_get.

Enumerator
GHOSTTY_TERMINAL_DATA_INVALID	Invalid data type. Never results in any data extraction.
GHOSTTY_TERMINAL_DATA_COLS	Terminal width in cells. Output type: uint16_t *
GHOSTTY_TERMINAL_DATA_ROWS	Terminal height in cells. Output type: uint16_t *
GHOSTTY_TERMINAL_DATA_CURSOR_X	Cursor column position (0-indexed). Output type: uint16_t *
GHOSTTY_TERMINAL_DATA_CURSOR_Y	Cursor row position within the active area (0-indexed). Output type: uint16_t *
GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP	Whether the cursor has a pending wrap (next print will soft-wrap). Output type: bool *
GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN	The currently active screen. Output type: GhosttyTerminalScreen *
GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE	Whether the cursor is visible (DEC mode 25). Output type: bool *
GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS	Current Kitty keyboard protocol flags. Output type: GhosttyKittyKeyFlags * (uint8_t *)
GHOSTTY_TERMINAL_DATA_SCROLLBAR	Scrollbar state for the terminal viewport. This may be expensive to calculate depending on where the viewport is (arbitrary pins are expensive). The caller should take care to only call this as needed and not too frequently. Output type: GhosttyTerminalScrollbar *
GHOSTTY_TERMINAL_DATA_CURSOR_STYLE	The current SGR style of the cursor. This is the style that will be applied to newly printed characters. Output type: GhosttyStyle *
GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING	Whether any mouse tracking mode is active. Returns true if any of the mouse tracking modes (X10, normal, button, or any-event) are enabled. Output type: bool *
GHOSTTY_TERMINAL_DATA_TITLE	The terminal title as set by escape sequences (e.g. OSC 0/2). Returns a borrowed string. The pointer is valid until the next call to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty string (len=0) is returned when no title has been set. Output type: GhosttyString *
GHOSTTY_TERMINAL_DATA_PWD	The terminal's current working directory as set by escape sequences (e.g. OSC 7). Returns a borrowed string. The pointer is valid until the next call to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty string (len=0) is returned when no pwd has been set. Output type: GhosttyString *
GHOSTTY_TERMINAL_DATA_TOTAL_ROWS	The total number of rows in the active screen including scrollback. Output type: size_t *
GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS	The number of scrollback rows (total rows minus viewport rows). Output type: size_t *
GHOSTTY_TERMINAL_DATA_WIDTH_PX	The total width of the terminal in pixels. This is cols * cell_width_px as set by ghostty_terminal_resize(). Output type: uint32_t *
GHOSTTY_TERMINAL_DATA_HEIGHT_PX	The total height of the terminal in pixels. This is rows * cell_height_px as set by ghostty_terminal_resize(). Output type: uint32_t *
GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND	The effective foreground color (override or default). Returns GHOSTTY_NO_VALUE if no foreground color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND	The effective background color (override or default). Returns GHOSTTY_NO_VALUE if no background color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_CURSOR	The effective cursor color (override or default). Returns GHOSTTY_NO_VALUE if no cursor color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_PALETTE	The current 256-color palette. Output type: GhosttyColorRgb[256] *
GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT	The default foreground color (ignoring any OSC override). Returns GHOSTTY_NO_VALUE if no default foreground color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT	The default background color (ignoring any OSC override). Returns GHOSTTY_NO_VALUE if no default background color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT	The default cursor color (ignoring any OSC override). Returns GHOSTTY_NO_VALUE if no default cursor color is set. Output type: GhosttyColorRgb *
GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT	The default 256-color palette (ignoring any OSC overrides). Output type: GhosttyColorRgb[256] *
GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT	The Kitty image storage limit in bytes for the active screen. A value of zero means the Kitty graphics protocol is disabled. Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time. Output type: uint64_t *
GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE	Whether the file medium is enabled for Kitty image loading on the active screen. Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time. Output type: bool *
GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE	Whether the temporary file medium is enabled for Kitty image loading on the active screen. Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time. Output type: bool *
GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM	Whether the shared memory medium is enabled for Kitty image loading on the active screen. Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time. Output type: bool *
GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS	The Kitty graphics image storage for the active screen. Returns a borrowed pointer to the image storage. The pointer is valid until the next mutating terminal call (e.g. ghostty_terminal_vt_write() or ghostty_terminal_reset()). Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time. Output type: GhosttyKittyGraphics *

Definition at line 606 of file terminal.h.

◆ GhosttyTerminalOption

enum GhosttyTerminalOption

Terminal option identifiers.

These values are used with ghostty_terminal_set() to configure terminal callbacks and associated state.

Enumerator
GHOSTTY_TERMINAL_OPT_USERDATA	Opaque userdata pointer passed to all callbacks. Input type: void*
GHOSTTY_TERMINAL_OPT_WRITE_PTY	Callback invoked when the terminal needs to write data back to the pty (e.g. in response to a DECRQM query or device status report). Set to NULL to ignore such sequences. Input type: GhosttyTerminalWritePtyFn
GHOSTTY_TERMINAL_OPT_BELL	Callback invoked when the terminal receives a BEL character (0x07). Set to NULL to ignore bell events. Input type: GhosttyTerminalBellFn
GHOSTTY_TERMINAL_OPT_ENQUIRY	Callback invoked when the terminal receives an ENQ character (0x05). Set to NULL to send no response. Input type: GhosttyTerminalEnquiryFn
GHOSTTY_TERMINAL_OPT_XTVERSION	Callback invoked when the terminal receives an XTVERSION query (CSI > q). Set to NULL to report the default "libghostty" string. Input type: GhosttyTerminalXtversionFn
GHOSTTY_TERMINAL_OPT_TITLE_CHANGED	Callback invoked when the terminal title changes via escape sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title change events. Input type: GhosttyTerminalTitleChangedFn
GHOSTTY_TERMINAL_OPT_SIZE	Callback invoked in response to XTWINOPS size queries (CSI 14/16/18 t). Set to NULL to silently ignore size queries. Input type: GhosttyTerminalSizeFn
GHOSTTY_TERMINAL_OPT_COLOR_SCHEME	Callback invoked in response to a color scheme device status report query (CSI ? 996 n). Return true and fill the out pointer to report the current scheme, or return false to silently ignore. Set to NULL to ignore color scheme queries. Input type: GhosttyTerminalColorSchemeFn
GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES	Callback invoked in response to a device attributes query (CSI c, CSI > c, or CSI = c). Return true and fill the out pointer with response data, or return false to silently ignore. Set to NULL to ignore device attributes queries. Input type: GhosttyTerminalDeviceAttributesFn
GHOSTTY_TERMINAL_OPT_TITLE	Set the terminal title manually. The string data is copied into the terminal. A NULL value pointer clears the title (equivalent to setting an empty string). Input type: GhosttyString*
GHOSTTY_TERMINAL_OPT_PWD	Set the terminal working directory manually. The string data is copied into the terminal. A NULL value pointer clears the pwd (equivalent to setting an empty string). Input type: GhosttyString*
GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND	Set the default foreground color. A NULL value pointer clears the default (unset). Input type: GhosttyColorRgb*
GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND	Set the default background color. A NULL value pointer clears the default (unset). Input type: GhosttyColorRgb*
GHOSTTY_TERMINAL_OPT_COLOR_CURSOR	Set the default cursor color. A NULL value pointer clears the default (unset). Input type: GhosttyColorRgb*
GHOSTTY_TERMINAL_OPT_COLOR_PALETTE	Set the default 256-color palette. The value must point to an array of exactly 256 GhosttyColorRgb values. A NULL value pointer resets to the built-in default palette. Input type: GhosttyColorRgb[256]*
GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT	Set the Kitty image storage limit in bytes. Applied to all initialized screens (primary and alternate). A value of zero disables the Kitty graphics protocol entirely, deleting all stored images and placements. A NULL value pointer is equivalent to zero (disables). Has no effect when Kitty graphics are disabled at build time. Input type: uint64_t*
GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE	Enable or disable Kitty image loading via the file medium. A NULL value pointer is a no-op. Has no effect when Kitty graphics are disabled at build time. Input type: bool*
GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE	Enable or disable Kitty image loading via the temporary file medium. A NULL value pointer is a no-op. Has no effect when Kitty graphics are disabled at build time. Input type: bool*
GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM	Enable or disable Kitty image loading via the shared memory medium. A NULL value pointer is a no-op. Has no effect when Kitty graphics are disabled at build time. Input type: bool*
GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES	Set the maximum bytes the APC handler will buffer for all protocols. This prevents malicious input from causing unbounded memory allocation. A NULL value pointer removes all overrides, reverting to the built-in defaults. Input type: size_t*
GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY	Set the maximum bytes the APC handler will buffer for Kitty graphics protocol data. A NULL value pointer removes the override, reverting to the built-in default. Input type: size_t*

Definition at line 399 of file terminal.h.

◆ GhosttyTerminalScreen

enum GhosttyTerminalScreen

Terminal screen identifier.

Identifies which screen buffer is active in the terminal.

Enumerator
GHOSTTY_TERMINAL_SCREEN_PRIMARY	The primary (normal) screen.
GHOSTTY_TERMINAL_SCREEN_ALTERNATE	The alternate screen.

Definition at line 225 of file terminal.h.

◆ GhosttyTerminalScrollViewportTag

enum GhosttyTerminalScrollViewportTag

Scroll viewport behavior tag.

Enumerator
GHOSTTY_SCROLL_VIEWPORT_TOP	Scroll to the top of the scrollback.
GHOSTTY_SCROLL_VIEWPORT_BOTTOM	Scroll to the bottom (active area).
GHOSTTY_SCROLL_VIEWPORT_DELTA	Scroll by a delta amount (up is negative).

Definition at line 183 of file terminal.h.

Function Documentation

◆ ghostty_terminal_free()

GHOSTTY_API void ghostty_terminal_free ( GhosttyTerminal terminal )

Free a terminal instance.

Releases all resources associated with the terminal. After this call, the terminal handle becomes invalid and must not be used.

Parameters

Terminal The terminal handle to free (may be NULL)

Examples: c-vt-formatter/src/main.c, c-vt-grid-traverse/src/main.c, and c-vt-kitty-graphics/src/main.c.

◆ ghostty_terminal_get()

GHOSTTY_API GhosttyResult ghostty_terminal_get	(	GhosttyTerminal	terminal,
		GhosttyTerminalData	data,
		void *	out )

Get data from a terminal instance.

Extracts typed data from the given terminal based on the specified data type. The output pointer must be of the appropriate type for the requested data kind. Valid data types and output types are documented in the GhosttyTerminalData enum.

Parameters

Terminal	The terminal handle (may be NULL)
data	The type of data to extract
out	Pointer to store the extracted data (type depends on data parameter)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal is NULL or the data type is invalid

Examples: c-vt-grid-traverse/src/main.c, and c-vt-kitty-graphics/src/main.c.

◆ ghostty_terminal_get_multi()

GHOSTTY_API GhosttyResult ghostty_terminal_get_multi	(	GhosttyTerminal	terminal,
		size_t	count,
		const GhosttyTerminalData *	keys,
		void **	values,
		size_t *	out_written )

Get multiple data fields from a terminal in a single call.

This is an optimization over calling ghostty_terminal_get() repeatedly, particularly useful in environments with high per-call overhead such as FFI or Cgo.

Each element in the keys array specifies a data kind, and the corresponding element in the values array receives the result. The type of each values[i] pointer must match the output type documented for keys[i].

Processing stops at the first error; on success out_written is set to count, on error it is set to the index of the failing key (i.e. the number of values successfully written).

Parameters

	Terminal	The terminal handle (may be NULL)
	count	Number of key/value pairs
	keys	Array of data kinds to query
	values	Array of output pointers (types must match each key's documented output type)
[out]	out_written	On return, receives the number of values successfully written (may be NULL)

Returns: GHOSTTY_SUCCESS if all queries succeed

◆ ghostty_terminal_grid_ref()

GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref	(	GhosttyTerminal	terminal,
		GhosttyPoint	point,
		GhosttyGridRef *	out_ref )

Resolve a point in the terminal grid to a grid reference.

Resolves the given point (which can be in active, viewport, screen, or history coordinates) to a grid reference for that location. Use ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell and row.

Lookups using the active and viewport tags are fast. The Screen and history tags may require traversing the full scrollback page list to resolve the y coordinate, so they can be expensive for large scrollback buffers.

This function isn't meant to be used as the core of render loop. It isn't built to sustain the framerates needed for rendering large screens. Use the render state API for that. This API is instead meant for less strictly performance-sensitive use cases.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	Point	The point specifying which cell to look up
[out]	out_ref	On success, set to the grid reference at the given point (may be NULL)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal is NULL or the point is out of bounds

Examples: c-vt-grid-traverse/src/main.c.

◆ ghostty_terminal_mode_get()

GHOSTTY_API GhosttyResult ghostty_terminal_mode_get	(	GhosttyTerminal	terminal,
		GhosttyMode	mode,
		bool *	out_value )

Get the current value of a terminal mode.

Returns the value of the mode identified by the given mode.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	mode	The mode identifying the mode to query
[out]	out_value	On success, set to true if the mode is set, false if it is reset

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal is NULL or the mode does not correspond to a known mode

◆ ghostty_terminal_mode_set()

GHOSTTY_API GhosttyResult ghostty_terminal_mode_set	(	GhosttyTerminal	terminal,
		GhosttyMode	mode,
		bool	value )

Set the value of a terminal mode.

Sets the mode identified by the given mode to the specified value.

Parameters

Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
mode	The mode identifying the mode to set
value	true to set the mode, false to reset it

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal is NULL or the mode does not correspond to a known mode

◆ ghostty_terminal_new()

GHOSTTY_API GhosttyResult ghostty_terminal_new	(	const GhosttyAllocator *	allocator,
		GhosttyTerminal *	terminal,
		GhosttyTerminalOptions	options )

Create a new terminal instance.

Parameters

Memory Management	Pointer to allocator, or NULL to use the default allocator
Terminal	Pointer to store the created terminal handle
options	Terminal initialization options

Returns: GHOSTTY_SUCCESS on success, or an error code on failure

Examples: c-vt-formatter/src/main.c, c-vt-grid-traverse/src/main.c, and c-vt-kitty-graphics/src/main.c.

◆ ghostty_terminal_point_from_grid_ref()

GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref	(	GhosttyTerminal	terminal,
		const GhosttyGridRef *	ref,
		GhosttyPointTag	tag,
		GhosttyPointCoordinate *	out )

Convert a grid reference back to a point in the given coordinate system.

This is the inverse of ghostty_terminal_grid_ref(): given a grid reference, it returns the x/y coordinates in the requested coordinate system (active, viewport, screen, or history).

The grid reference must have been obtained from the same terminal instance. Like all grid references, it is only valid until the next mutating terminal call.

Not every grid reference is representable in every coordinate system. For example, a cell in scrollback history cannot be expressed in active coordinates, and a cell that has scrolled off the visible area cannot be expressed in viewport coordinates. In these cases, the function returns GHOSTTY_NO_VALUE.

Parameters

	Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
	ref	Pointer to the grid reference to convert
	tag	The target coordinate system
[out]	out	On success, set to the coordinate in the requested system (may be NULL)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal or ref is NULL/invalid, GHOSTTY_NO_VALUE if the ref falls outside the requested coordinate system

◆ ghostty_terminal_reset()

GHOSTTY_API void ghostty_terminal_reset ( GhosttyTerminal terminal )

Perform a full reset of the terminal (RIS).

Resets all terminal state back to its initial configuration, including modes, scrollback, scrolling region, and screen contents. The terminal dimensions are preserved.

Parameters

Terminal The terminal handle (may be NULL, in which case this is a no-op)

◆ ghostty_terminal_resize()

GHOSTTY_API GhosttyResult ghostty_terminal_resize	(	GhosttyTerminal	terminal,
		uint16_t	cols,
		uint16_t	rows,
		uint32_t	cell_width_px,
		uint32_t	cell_height_px )

Resize the terminal to the given dimensions.

Changes the number of columns and rows in the terminal. The primary screen will reflow content if wraparound mode is enabled; the alternate screen does not reflow. If the dimensions are unchanged, this is a no-op.

This also updates the terminal's pixel dimensions (used for image protocols and size reports), disables synchronized output mode (allowed by the spec so that resize results are shown immediately), and sends an in-band size report if mode 2048 is enabled.

Parameters

Terminal	The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
cols	New width in cells (must be greater than zero)
rows	New height in cells (must be greater than zero)
cell_width_px	Width of a single cell in pixels
cell_height_px	Height of a single cell in pixels

Returns: GHOSTTY_SUCCESS on success, or an error code on failure

Examples: c-vt-kitty-graphics/src/main.c.

◆ ghostty_terminal_scroll_viewport()

GHOSTTY_API void ghostty_terminal_scroll_viewport	(	GhosttyTerminal	terminal,
		GhosttyTerminalScrollViewport	behavior )

Scroll the terminal viewport.

Scrolls the terminal's viewport according to the given behavior. When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in the value union to specify the number of rows to scroll (negative for up, positive for down). For other behaviors, the value is ignored.

Parameters

Terminal	The terminal handle (may be NULL, in which case this is a no-op)
behavior	The scroll behavior as a tagged union

◆ ghostty_terminal_set()

GHOSTTY_API GhosttyResult ghostty_terminal_set	(	GhosttyTerminal	terminal,
		GhosttyTerminalOption	option,
		const void *	value )

Set an option on the terminal.

Configures terminal callbacks and associated state such as the write_pty callback and userdata pointer. The value is passed directly for pointer types (callbacks, userdata) or as a pointer to the value for non-pointer types (e.g. GhosttyString*). NULL clears the option to its default.

Callbacks are invoked synchronously during ghostty_terminal_vt_write(). Callbacks must not call ghostty_terminal_vt_write() on the same terminal (no reentrancy).

Parameters

Terminal	The terminal handle (may be NULL, in which case this is a no-op)
option	The option to set
value	Pointer to the value to set (type depends on the option), or NULL to clear the option

Examples: c-vt-kitty-graphics/src/main.c.

◆ ghostty_terminal_vt_write()

GHOSTTY_API void ghostty_terminal_vt_write	(	GhosttyTerminal	terminal,
		const uint8_t *	data,
		size_t	len )

Write VT-encoded data to the terminal for processing.

Feeds raw bytes through the terminal's VT stream parser, updating terminal state accordingly. By default, sequences that require output (queries, device status reports) are silently ignored. Use ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_WRITE_PTY to install a callback that receives response data.

This never fails. Any erroneous input or errors in processing the input are logged internally but do not cause this function to fail because this input is assumed to be untrusted and from an external source; so the primary goal is to keep the terminal state consistent and not allow malformed input to corrupt or crash.

Parameters

Terminal	The terminal handle
data	Pointer to the data to write
len	Length of the data in bytes

Examples: c-vt-formatter/src/main.c, c-vt-grid-traverse/src/main.c, and c-vt-kitty-graphics/src/main.c.

Detailed Description

Example: VT stream processing

Effects

Defining a write_pty callback

Defining a bell callback

Defining a title_changed callback

Registering effects and processing VT data

Color Theme

Default Colors

Reading colors

Setting a color theme

Reading effective and default colors

Full example with OSC overrides

Typedefs

Enumerations

Functions

Data Structures

Typedef Documentation

◆ GhosttyTerminal

◆ GhosttyTerminalBellFn

◆ GhosttyTerminalColorSchemeFn

◆ GhosttyTerminalDeviceAttributesFn

◆ GhosttyTerminalEnquiryFn

◆ GhosttyTerminalSizeFn

◆ GhosttyTerminalTitleChangedFn

◆ GhosttyTerminalWritePtyFn

◆ GhosttyTerminalXtversionFn

Enumeration Type Documentation

◆ GhosttyColorScheme

◆ GhosttyTerminalData

◆ GhosttyTerminalOption

◆ GhosttyTerminalScreen

◆ GhosttyTerminalScrollViewportTag

Function Documentation

◆ ghostty_terminal_free()

◆ ghostty_terminal_get()

◆ ghostty_terminal_get_multi()

◆ ghostty_terminal_grid_ref()

◆ ghostty_terminal_mode_get()

◆ ghostty_terminal_mode_set()

◆ ghostty_terminal_new()

◆ ghostty_terminal_point_from_grid_ref()

◆ ghostty_terminal_reset()

◆ ghostty_terminal_resize()

◆ ghostty_terminal_scroll_viewport()

◆ ghostty_terminal_set()

◆ ghostty_terminal_vt_write()