Terminal

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_PWD_CHANGED	GhosttyTerminalPwdChangedFn	Pwd change via OSC 7 / OSC 9 / OSC 1337
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(*	GhosttyTerminalPwdChangedFn) (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_ROW , 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	GhosttyTerminalCursorStyle { GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0 , GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1 , GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2 , GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3 , GHOSTTY_TERMINAL_CURSOR_STYLE_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_SELECTION = 21 , GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22 , GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23 ,   GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24 , GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25 , 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_SELECTION = 31 ,   GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32 , 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_grid_ref_track (GhosttyTerminal terminal, GhosttyPoint point, GhosttyTrackedGridRef *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-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-kitty-graphics/src/main.c, and c-vt-selection-gesture/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 302 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 319 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 340 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 358 of file terminal.h.

GhosttyTerminalPwdChangedFn

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

Callback function type for pwd_changed.

Called when the terminal pwd (current working directory) changes via escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.

The terminal stores whatever bytes the shell emitted, without parsing. That means for OSC 7 the value is the raw URI (typically file://...); for OSC 9/OSC 1337 it is typically a bare path. The embedder is responsible for decoding any URI scheme or host if it cares about them.

The callback also fires when the shell clears the pwd (e.g. an empty OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length string.

Parameters

Terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 416 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 375 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 391 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 434 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 453 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.

GhosttyTerminalCursorStyle

enum GhosttyTerminalCursorStyle

Visual style of the terminal cursor.

Enumerator
GHOSTTY_TERMINAL_CURSOR_STYLE_BAR	Bar cursor (DECSCUSR 5, 6).
GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK	Block cursor (DECSCUSR 1, 2).
GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE	Underline cursor (DECSCUSR 3, 4).
GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW	Hollow block cursor.

Definition at line 259 of file terminal.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 is amortized O(1): the total is maintained incrementally as the terminal is modified and the viewport offset is cached. The first read after the viewport moves to an arbitrary position that isn't an absolute row (e.g. scrolling to a selection) may cost O(pages) to compute the offset, after which it is cached again. There is intentionally no change notification for scroll state. Callers building scrollbars should poll this once per frame or per write batch and diff the result to detect changes; this is what Ghostty's own renderer does. 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 *
GHOSTTY_TERMINAL_DATA_SELECTION	The active screen's current selection. On success, writes an untracked snapshot of the terminal-owned selection to the caller-provided GhosttySelection. The GhosttySelection struct is caller-owned and may be kept, but the grid references inside it are untracked borrowed references into the active screen. They are only valid until the next mutating terminal call, such as ghostty_terminal_set(), ghostty_terminal_vt_write(), ghostty_terminal_resize(), or ghostty_terminal_reset(). Returns GHOSTTY_NO_VALUE when there is no active selection. Output type: GhosttySelection *
GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE	Whether the viewport is currently pinned to the active area. This is true when the viewport is following the active terminal area, and false when the user has scrolled into history. Output type: bool *

Definition at line 725 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*
GHOSTTY_TERMINAL_OPT_SELECTION	Set the active screen selection. The value must point to a GhosttySelection whose grid references are valid for this terminal's active screen at the time of the call. The terminal copies the selection immediately and converts it to terminal-owned tracked state, so the GhosttySelection struct and its untracked grid references do not need to outlive this call. Passing NULL clears the active screen selection. Input type: GhosttySelection*
GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE	Set the default cursor style used by DECSCUSR reset (CSI 0 q). A NULL value pointer resets to the built-in default block cursor. Input type: GhosttyTerminalCursorStyle*
GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK	Set whether the default cursor should blink when reset by DECSCUSR (CSI 0 q). A NULL value pointer resets to the built-in default of not blinking. Input type: bool*
GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL	Enable or disable Glyph Protocol APC handling. When disabled, Glyph Protocol APC sequences are ignored and no support/query/register/clear responses are emitted. Disabling also clears the terminal session's glyph glossary. A NULL value pointer is a no-op. Input type: bool*
GHOSTTY_TERMINAL_OPT_PWD_CHANGED	Callback invoked when the terminal pwd changes via escape sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL to ignore pwd change events. Input type: GhosttyTerminalPwdChangedFn

Definition at line 464 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 245 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).
GHOSTTY_SCROLL_VIEWPORT_ROW	Scroll to an absolute row offset from the top of the scrollable area. Row 0 is the top of the scrollback and the requested row becomes the first visible row of the viewport. The value is clamped so the viewport never scrolls beyond the top of the active area. If the terminal has no scrollback (e.g. the alternate screen is active), the viewport always remains on the active area. This is the same row space as the offset field of GhosttyTerminalScrollbar, so a scrollbar position obtained from GHOSTTY_TERMINAL_DATA_SCROLLBAR round-trips cleanly.

Definition at line 185 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-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-kitty-graphics/src/main.c, and c-vt-selection-gesture/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, and c-vt-selection-gesture/src/main.c.

ghostty_terminal_grid_ref_track()

GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track	(	GhosttyTerminal	terminal,
		GhosttyPoint	point,
		GhosttyTrackedGridRef *	out_ref )

Create an owned tracked grid reference for a terminal point.

This is the tracked variant of ghostty_terminal_grid_ref(). The returned handle follows the referenced cell as the terminal's page list is modified: scrolling, pruning, resize/reflow, and other page-list operations update the tracked reference automatically.

The reference is attached to the terminal screen/page-list that is active at creation time.

If the point is outside the requested coordinate space, this returns GHOSTTY_INVALID_VALUE and writes NULL to out_ref.

The returned handle must be freed with ghostty_tracked_grid_ref_free(). If the terminal is freed first, the handle remains valid only for tracked-grid-ref APIs: it reports no value and can still be freed.

Parameters

	Terminal	Terminal instance.
	Point	Point to track.
[out]	out_ref	On success, receives the tracked reference handle.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if terminal, point, or out_ref is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails.

Examples

c-vt-grid-ref-tracked/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-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-kitty-graphics/src/main.c, and c-vt-selection-gesture/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)

Examples

c-vt-grid-ref-tracked/src/main.c.

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). When using GHOSTTY_SCROLL_VIEWPORT_ROW, set the row field to the absolute row offset from the top of the scrollable area (the same row space as the offset field of GhosttyTerminalScrollbar). 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-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-kitty-graphics/src/main.c, and c-vt-selection-gesture/src/main.c.