 |
libghostty-vt 0.0.0
|
|
libghostty-vt 0.0.0
|
Create a terminal, write VT data to it, and read its state. More...
Create a terminal, write VT data to it, and read its state.
A GhosttyTerminal is a whole terminal emulator: you write VT data into it, and it keeps the screen, scrollback, cursor, styles, and modes.
Nearly everything in this library starts here. All you need to make one is a size. It doesn't draw and it doesn't talk to a pty. Both of those are yours. If you only want one parser or encoder, the Building Blocks work without a terminal.
Full program: c-vt-stream/src/main.c
The guides cover the rest: Effects for what programs ask of the terminal, Colors, Scrollback, and Custom Sequences.
Typedefs | |
| typedef struct GhosttyTerminalImpl * | GhosttyTerminal |
Data Structures | |
| union | GhosttyTerminalScrollViewportValue |
| struct | GhosttyTerminalScrollViewport |
| struct | GhosttyTerminalWriteStop |
| struct | GhosttyTerminalScrollbar |
| struct | GhosttyTerminalMemoryUsage |
| struct | GhosttyTerminalModeConfig |
Lifecycle | |
| GHOSTTY_API GhosttyResult | ghostty_terminal_new (const GhosttyAllocator *allocator, GhosttyTerminal *terminal, uint16_t cols, uint16_t rows) |
| 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) |
Options | |
| GHOSTTY_API GhosttyResult | ghostty_terminal_set (GhosttyTerminal terminal, GhosttyTerminalOption option, const void *value) |
Writing | |
| GHOSTTY_API void | ghostty_terminal_vt_write (GhosttyTerminal terminal, const uint8_t *data, size_t len) |
| GHOSTTY_API GhosttyResult | ghostty_terminal_vt_write_until (GhosttyTerminal terminal, const uint8_t *data, size_t len, uint32_t boundaries, GhosttyTerminalWriteStop *out) |
| GHOSTTY_API GhosttyResult | ghostty_terminal_continuation_write (GhosttyTerminal terminal, GhosttyWriter writer) |
| GHOSTTY_API GhosttyResult | ghostty_terminal_continuation_buf (GhosttyTerminal terminal, uint8_t *buf, size_t buf_len, size_t *out_written) |
| GHOSTTY_API GhosttyResult | ghostty_terminal_continuation_alloc (GhosttyTerminal terminal, const GhosttyAllocator *allocator, uint8_t **out_ptr, size_t *out_len) |
Scrolling | |
| GHOSTTY_API GhosttyResult | ghostty_terminal_scroll_viewport (GhosttyTerminal terminal, GhosttyTerminalScrollViewport behavior) |
Compression | |
| GHOSTTY_API GhosttyResult | ghostty_terminal_compression_activity (GhosttyTerminal terminal, uint64_t *out_activity) |
| GHOSTTY_API GhosttyResult | ghostty_terminal_compress (GhosttyTerminal terminal, GhosttyTerminalCompressionMode mode, GhosttyTerminalCompressionResult *out_result) |
Data | |
| 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) |
Grid Access | |
| 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) |
| typedef struct GhosttyTerminalImpl* GhosttyTerminal |
Opaque handle to a terminal instance.
| enum GhosttyCursorStyle |
The shape of the cursor.
Programs change the cursor's shape with the DECSCUSR escape sequence (CSI Ps SP q). Set the shape that DECSCUSR 0 restores with GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE. Read the shape to draw with GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE.
A point in the VT stream where ghostty_terminal_vt_write_until() can stop.
The values are bit flags. Combine them with | to stop at any of several boundaries.
Most boundaries mark the first or last byte of a control string: an APC, DCS or OSC sequence, made of an introducer, some content, and a terminator. GROUND is different. It marks the state between sequences rather than a byte inside one.
Terminal protocols spell control bytes two ways, and both are recognized. A 7-bit introducer is ESC followed by one byte, such as ESC ] for OSC. The 8-bit form is a single byte in the range 0x80 to 0x9F, such as 0x9D for OSC. The string terminator ST is ESC \\endiskip or the single byte 0x9C.
| Enumerator | |
|---|---|
| GHOSTTY_TERMINAL_BOUNDARY_GROUND | The stream is not inside any escape sequence or partial UTF-8 character. This is a safe point to insert your own sequences. Ground is a state, not an event. If the stream is already at ground, the call stops immediately and consumes nothing. |
| GHOSTTY_TERMINAL_BOUNDARY_APC_START | The byte that started an APC string: _ after ESC, or 0x9F. SOS (X or 0x98) and PM (^ or 0x9E) strings also report this boundary, because the parser handles all three the same way. Check GhosttyTerminalWriteStop.byte to tell them apart. |
| GHOSTTY_TERMINAL_BOUNDARY_APC_END | The byte that ended an APC, SOS or PM string. |
| GHOSTTY_TERMINAL_BOUNDARY_DCS_START | The byte that started a DCS string: P after ESC, or 0x90. A DCS has a header before its payload: parameters, intermediates and a final byte, in the same shape as a CSI sequence. The stop lands on the introducer, so the header follows it. A 0x90 inside the header restarts the header without leaving the string, so it does not stop. |
| GHOSTTY_TERMINAL_BOUNDARY_DCS_END | The byte that ended a DCS string, whether it was still in its header or already in its payload. A DCS cut short in its header reports this without ever having had a payload. |
| GHOSTTY_TERMINAL_BOUNDARY_OSC_START | The byte that started an OSC string: ] after ESC, or 0x9D. |
| GHOSTTY_TERMINAL_BOUNDARY_OSC_END | The byte that ended an OSC string. This is reported for every OSC, including ones the terminal does not understand. |
Definition at line 204 of file terminal.h.
Amount of compression work to perform before returning.
Definition at line 68 of file terminal.h.
Scheduling result from terminal compression.
Definition at line 82 of file terminal.h.
| 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 mutating terminal call. 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 mutating terminal call. 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. ghostty_terminal_get() returns GHOSTTY_UNSUPPORTED for this data 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. ghostty_terminal_get() returns GHOSTTY_UNSUPPORTED for this data when Kitty graphics are disabled at build time. Output type: bool * |
| GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE | The directory allowed for Kitty image loading via the temporary file medium on the active screen. The string is empty when the medium is disabled. ghostty_terminal_get() returns GHOSTTY_UNSUPPORTED for this data when Kitty graphics are disabled at build time. Output type: GhosttyString * |
| GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM | Whether the shared memory medium is enabled for Kitty image loading on the active screen. ghostty_terminal_get() returns GHOSTTY_UNSUPPORTED for this data 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()). ghostty_terminal_get() returns GHOSTTY_UNSUPPORTED for this data 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 your 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 * |
| GHOSTTY_TERMINAL_DATA_VT_PROCESSING_ERROR | Whether VT processing encountered a non-gracefully handled error that may have prevented a terminal-owned semantic update. Processing remains best-effort, and ghostty_terminal_reset() does not clear it. Gracefully handled protocol failures, configured limits, malformed or unsupported input, and failures limited to external effects or query responses do not set it. This can't currently be unset. This is purely informational to consumers if there was some error that happened at some point during VT processing. Output type: bool * |
| GHOSTTY_TERMINAL_DATA_SCROLLBACK_MAX_BYTES | The configured maximum scrollback allocation in bytes. This always reports the primary screen's configured value, including while an alternate screen is active. Returns GHOSTTY_NO_VALUE when the configured byte limit is unlimited. Output type: size_t * |
| GHOSTTY_TERMINAL_DATA_SCROLLBACK_MAX_LINES | The configured maximum number of physical scrollback lines. This always reports the primary screen's configured value, including while an alternate screen is active. Returns GHOSTTY_NO_VALUE when the configured line limit is unlimited. Output type: size_t * |
| GHOSTTY_TERMINAL_DATA_CONTINUATION_MAX_BYTES | The configured maximum retained VT continuation size in bytes. A value of zero means continuation tracking is disabled. This reports the configured limit even when a current unfinished continuation is temporarily unavailable. Output type: size_t * |
| GHOSTTY_TERMINAL_DATA_MODE | Get the current value of a terminal mode. You must initialize the mode field. On success, the value field is updated with the current value. A NULL pointer or unknown mode returns GHOSTTY_INVALID_VALUE. Input/output type: GhosttyTerminalModeConfig * |
| GHOSTTY_TERMINAL_DATA_VT_GROUND | Whether VT processing is at ground. Ground is when the stream isn't in the middle of any type of sequence: UTF-8, ESC, CSI, OSC, etc. It is the stateless point of the stream. This is useful to know because it is a point at which you can safely insert out-of-band VT sequences. For example, while reading from a pty if you want to make your own changes, you can wait until the pty input reaches ground, then write yours. Output type: bool * |
| GHOSTTY_TERMINAL_DATA_CURSOR_AT_PROMPT | Whether the cursor is currently at a semantic shell prompt or input area. This depends on semantic prompt markers such as OSC 133. Returns false when semantic prompt information is unavailable or the alternate screen is active. Output type: bool * |
| GHOSTTY_TERMINAL_DATA_CLIPBOARD_WRITE_MAX_BYTES | The configured maximum decoded bytes per Kitty clipboard protocol (OSC 5522) write transaction. See GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE_MAX_BYTES. Output type: size_t * |
| GHOSTTY_TERMINAL_DATA_MOUSE_SHAPE | The mouse pointer shape requested by the application through OSC 22. Initially GHOSTTY_MOUSE_SHAPE_TEXT. Excludes host hover overrides. Output type: GhosttyMouseShape * |
| GHOSTTY_TERMINAL_DATA_MEMORY_USAGE | How much memory the terminal holds. See GhosttyTerminalMemoryUsage for what each field means. Set the struct's size field before the call, for example with GHOSTTY_INIT_SIZED(). If size is too small, this returns GHOSTTY_INVALID_VALUE and leaves the struct unchanged. This never decompresses scrollback, but it does look at every page, so avoid reading it after every write. Output type: GhosttyTerminalMemoryUsage * |
Definition at line 2658 of file terminal.h.
Terminal option identifiers.
These values are used with ghostty_terminal_set() to configure terminal callbacks and associated state.
| Enumerator | |
|---|---|
| GHOSTTY_TERMINAL_OPT_INVALID | Not a real option. ghostty_terminal_set() returns GHOSTTY_INVALID_VALUE for it. Its value is 0, so a zeroed or uninitialized variable is never mistaken for a real option. |
| GHOSTTY_TERMINAL_OPT_USERDATA | Opaque userdata pointer passed to all callbacks. NULL by default. 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, device status report, or VT-driven mode 2048 enable). 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/19 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. The default is 10 MB (10,000,000 bytes), and a NULL value pointer restores it. Values too large for the platform's address space are treated as the largest possible limit. ghostty_terminal_set() returns GHOSTTY_UNSUPPORTED for this option 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. Disabled by default, and a NULL value pointer disables it again. ghostty_terminal_set() returns GHOSTTY_UNSUPPORTED for this option when Kitty graphics are disabled at build time. Input type: bool* |
| GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE | Enable Kitty image loading via the temporary file medium, restricted to the provided directory. The string data is copied into the terminal. Disabled by default, and a NULL value pointer disables it again. ghostty_terminal_set() returns GHOSTTY_UNSUPPORTED for this option when Kitty graphics are disabled at build time. Input type: GhosttyString* |
| GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM | Enable or disable Kitty image loading via the shared memory medium. Disabled by default, and a NULL value pointer disables it again. ghostty_terminal_set() returns GHOSTTY_UNSUPPORTED for this option 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: GhosttyCursorStyle* |
| 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. Enabled by default, and a NULL value pointer enables it again. 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 |
| GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE | Callback invoked when the running program performs a clipboard write. OSC 52, iTerm2 OSC 1337 Copy, and Kitty clipboard (OSC 5522) writes are normalized to an atomic set of decoded MIME representations. Set to NULL to ignore clipboard writes (Kitty clipboard writes are then refused with ENOSYS). Clipboard read requests are delivered to GHOSTTY_TERMINAL_OPT_CLIPBOARD_READ instead. Input type: GhosttyTerminalClipboardWriteFn |
| GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES | Set the maximum scrollback allocation in bytes. This is an estimate. Internally, libghostty only prunes bytes up to a "page"-granularity. A page is the minimum allocated unit of grid space within Ghostty. A page at the time of writing these docs is about 400KB, so the byte limit will be within this delta. This works alongside the line limit configuration. If both are set, the first-reached limit is used first. Both limits are dependent on external state (byte limit can be reached with less lines if more styles are used for example, line limit can be reached with a narrower terminal viewport). So, they are useful together. Lowering the limit immediately removes eligible complete historical pages. A value of zero disables scrollback and erases retained history. The default is 10,000 bytes. Because history is kept in whole pages, this is rounded up to one page in practice. Pass SIZE_MAX for no byte limit, or NULL to restore the default: size_t unlimited = SIZE_MAX;
ghostty_terminal_set(terminal,
GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES, &unlimited);
// Back to the default of 10,000 bytes.
ghostty_terminal_set(terminal,
GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal, GhosttyTerminalOption option, const void *value) @ GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES Definition terminal.h:2339 Input type: size_t* |
| GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_LINES | Set the maximum number of physical lines retained in scrollback. This is an estimate. Internally, libghostty only prunes lines up to a "page"-granularity. A page is the minimum allocated unit of grid space within Ghostty. As a result, the actual available scrollback lines will almost always be higher than configured. The magnitude of the difference depends on the number of used styles, graphemes, etc. since the row-count in a page is dynamic based on that. In general, it ranges from dozens to a hundred or so lines. This works alongside the line limit configuration. If both are set, the first-reached limit is used first. Both limits are dependent on external state (byte limit can be reached with less lines if more styles are used for example, line limit can be reached with a narrower terminal viewport). So, they are useful together. Lowering the limit immediately removes eligible complete historical pages. There is no line limit by default. Pass SIZE_MAX or NULL to remove a line limit you set earlier. Input type: size_t* |
| GHOSTTY_TERMINAL_OPT_DESKTOP_NOTIFICATION | Callback invoked when the running program requests a desktop notification via OSC 9 or OSC 777. Set to NULL to ignore desktop notification requests. Input type: GhosttyTerminalDesktopNotificationFn |
| GHOSTTY_TERMINAL_OPT_PROGRESS_REPORT | Callback invoked when the running program reports progress via OSC 9;4. Set to NULL to ignore progress reports. Input type: GhosttyTerminalProgressReportFn |
| GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES | Set the maximum number of replay-safe VT continuation bytes retained. Continuation bytes reconstruct an escape sequence or UTF-8 codepoint which was unfinished at the end of the most recent VT write call. They are used automatically by terminal snapshots and may also be exported directly with the continuation APIs. Tracking is disabled by default. A nonzero value enables tracking and sets its byte limit. Passing NULL or a pointer to zero disables tracking. Lowering the limit below an already-retained continuation, or enabling tracking while the parser is already unfinished, makes the current continuation unavailable because earlier bytes cannot be reconstructed. Tracking recovers automatically after a later write reaches the ground state or contains a fresh replay start. Input type: size_t* |
| GHOSTTY_TERMINAL_OPT_TITLE_REPORT | Enable window title reports in response to CSI 21 t. This is disabled by default because a running program can set a title and query it back into the pty input stream, potentially injecting commands that execute after user interaction. Passing NULL or a pointer to false disables title reporting. Input type: bool* |
| GHOSTTY_TERMINAL_OPT_MODE_DEFAULT | Set the reset default for a terminal mode. This unconditionally updates both the current value and the value restored by a terminal reset. RIS restores every mode, and DECSTR only a subset. Some recognized modes represent transitions or mirror additional terminal state and cannot safely be configured as reset defaults. Those modes return GHOSTTY_INVALID_VALUE. A NULL value pointer also returns GHOSTTY_INVALID_VALUE. Input type: GhosttyTerminalModeConfig* |
| GHOSTTY_TERMINAL_OPT_MODE | Set the current value of a terminal mode. This does not change the value restored by a reset (RIS or DECSTR). A NULL value pointer or unknown mode returns GHOSTTY_INVALID_VALUE. Input type: GhosttyTerminalModeConfig* |
| GHOSTTY_TERMINAL_OPT_UNKNOWN_SEQUENCE | Callback for escape sequences that libghostty-vt does not implement. Set to NULL to stop receiving them. GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES must also be set, or the callback is never called. See Handling sequences we don't implement for an example. Input type: GhosttyTerminalUnknownSequenceFn |
| GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES | The most bytes of each unsupported sequence to keep and pass to the GHOSTTY_TERMINAL_OPT_UNKNOWN_SEQUENCE callback. The same limit applies to APC and OSC sequences. Zero, the default, turns unsupported sequence reporting off. A NULL value pointer also sets it to zero. A sequence longer than the limit is still reported. Its content holds the first bytes up to the limit, and truncated is true. Choose a limit that fits the largest sequence you expect. Unknown OSC sequences up to 2048 bytes are kept in a buffer the terminal already owns, so limits up to 2048 add no memory allocations for OSC. Larger limits allocate memory for each unknown OSC sequence. Unknown APC sequences are always kept in allocated memory. Input type: size_t* |
| GHOSTTY_TERMINAL_OPT_TERMINFO_NAME | Set the name of the terminfo entry this terminal runs as, reported in response to an XTGETTCAP query for "TN" (e.g. "xterm-256color"). The string data is copied into the terminal. A NULL value pointer clears the name (equivalent to setting an empty string). A name longer than 128 bytes returns GHOSTTY_INVALID_VALUE. If this is unset then we don't report anything for an XTGETTCAP TN query, because we don't know what the embedding terminal around libghostty is advertising itself as. Input type: GhosttyString* |
| GHOSTTY_TERMINAL_OPT_CLIPBOARD_READ | Callback invoked when the running program requests clipboard contents via OSC 52 with a "?" payload or a Kitty clipboard (OSC 5522) read. The read is synchronous and must be answered before the callback returns. Set to NULL (the default) to ignore OSC 52 read requests and refuse OSC 5522 reads with EPERM. Input type: GhosttyTerminalClipboardReadFn |
| GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE_MAX_BYTES | Set the maximum total decoded bytes a single Kitty clipboard protocol (OSC 5522) write transaction may accumulate. The limit is captured when a transaction begins; an in-flight transaction keeps the limit it started with. Data beyond the limit fails the whole transaction with EFBIG. The transaction is discarded, later write-related packets are ignored until a new write begins, and nothing reaches the clipboard write callback. Transactions are buffered in memory, so this limit bounds how much memory a single write can make the terminal allocate. Pass SIZE_MAX to remove the limit. A NULL value pointer reverts to the built-in default of 64MiB, the minimum required by the protocol. This limit doesn't apply to OSC 52 writes, which are bounded by the maximum length of an escape sequence instead. Input type: size_t* |
| GHOSTTY_TERMINAL_OPT_RESIZE_PULL_SCROLLBACK | Set whether a resize may pull rows out of scrollback back into the active area. When true, growing rows reveals scrollback if the cursor is on the bottom row, and a column reflow that needs fewer rows reveals scrollback as well. When false, growing rows always appends blank rows at the bottom and a column reflow keeps the top of the active area on the same content, so a line that is fully in scrollback stays there. A soft-wrapped line with at least one row still in the active area may still unwrap back into view. Set this to false when the pty keeps its own screen buffer without scrollback, since it cannot pull rows back and will otherwise disagree with the terminal about the screen contents after a resize. Windows ConPTY is the motivating case. This is preserved across a full reset (RIS). A NULL value pointer resets to the built-in default of true. Input type: bool* |
| GHOSTTY_TERMINAL_OPT_RENDER_HOLD | Callback invoked when the running program asks the terminal to stop updating the screen and when it allows updates again. Today this is driven by synchronized output (mode 2026). Set to NULL to ignore these events. See Render holds for how to use this in a renderer. Input type: GhosttyTerminalRenderHoldFn |
| GHOSTTY_TERMINAL_OPT_SEMANTIC_PROMPT | Callback invoked when the shell reports a step of a command: a prompt starts, input starts, output starts, or the command ends. Set to NULL to ignore these events. Input type: GhosttyTerminalSemanticPromptFn |
| GHOSTTY_TERMINAL_OPT_RESET | Callback invoked after the running program performs a full reset (RIS, ESC c). Set to NULL to ignore resets. Input type: GhosttyTerminalResetFn |
| GHOSTTY_TERMINAL_OPT_XT_CHECKSUM_REPORT | Enable checksum reports in response to DECRQCRA (CSI Pi ; Pg ; Pt ; Pl ; Pb ; Pr * y). This is disabled by default because a running program can checksum the screen one cell at a time and so read back everything on it, including output from other programs. Passing NULL or a pointer to false disables checksum reporting. While this is disabled, XTCHECKSUM (CSI Ps # y), which changes how the checksum is calculated, is ignored as well. Input type: bool* |
| GHOSTTY_TERMINAL_OPT_XT_CHECKSUM_EXTENSION | Set how the DECRQCRA checksum is calculated after a reset (RIS or DECSTR). This also changes the current calculation. The value holds the same bits as XTCHECKSUM (CSI Ps # y) and xterm's checksumExtension resource, which a running program can still use to change the calculation until the next reset:
Zero, or passing NULL, is the calculation of a real DEC terminal. Values above 31 return GHOSTTY_INVALID_VALUE. Input type: uint8_t* |
| GHOSTTY_TERMINAL_OPT_PROGRAM_STATUS | Callback invoked when the running program sends a program status report via OSC 7501. Set to NULL to ignore these reports. Programs may ask whether the terminal supports the protocol by sending OSC 7501 ; ?. While this callback is set, the terminal answers through GHOSTTY_TERMINAL_OPT_WRITE_PTY with ? followed by the states and kinds it accepts: program: ESC ] 7501 ; ? ST
terminal: ESC ] 7501 ; ?:states=idle,working,done,blocked,error:kinds=permission,question,auth ST
While this callback is NULL, the query gets no reply, so a program that asks sees the protocol as unsupported. Asking is optional, so programs may send reports anyway. Those are dropped. Set a write_pty callback too, or programs never see the reply. Input type: GhosttyTerminalProgramStatusFn |
| GHOSTTY_TERMINAL_OPT_RESIZE_WINDOW | Callback invoked when the running program asks to resize the window, such as with CSI 8 ; rows ; columns t. Set to NULL to ignore resize requests. Input type: GhosttyTerminalResizeWindowFn |
Definition at line 2027 of file terminal.h.
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 177 of file terminal.h.
Scroll viewport behavior tag.
| Enumerator | |
|---|---|
| GHOSTTY_TERMINAL_SCROLL_VIEWPORT_TOP | Scroll to the top of the scrollback. |
| GHOSTTY_TERMINAL_SCROLL_VIEWPORT_BOTTOM | Scroll to the bottom (active area). |
| GHOSTTY_TERMINAL_SCROLL_VIEWPORT_DELTA | Scroll by a delta amount (up is negative). |
| GHOSTTY_TERMINAL_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. |
| GHOSTTY_TERMINAL_SCROLL_VIEWPORT_DELTA_PROMPT | Scroll by a number of prompts relative to the viewport top. Negative values move backward and positive values move forward. Requires semantic prompt markers from the shell. Zero or no matching prompt is a no-op. If fewer prompts remain than requested, move to the last matching prompt, clamped to the active area. Moving forward through a final prompt continuation can snap to the active area even when there is no newer prompt. |
Definition at line 99 of file terminal.h.
How a control string ended.
| Enumerator | |
|---|---|
| GHOSTTY_TERMINAL_STRING_END_ST_ESC | ESC, the first byte of the string terminator ESC \\endiskip. The ESC is consumed but the \\endiskip after it is not. Pass the \\endiskip as the first byte of your next write, where it completes the terminator. If you forward the stream elsewhere, forward the ESC along with the string. |
| GHOSTTY_TERMINAL_STRING_END_ST_C1 | 0x9C, the 8-bit string terminator. The stream is now at ground. Inside an OSC, and inside a DCS once its header is complete, 0x9C is content rather than a terminator. So this is only reported for an APC or for a DCS still in its header. |
| GHOSTTY_TERMINAL_STRING_END_CANCELLED | CAN (0x18) or SUB (0x1A) cancelled the string. The stream is now at ground. The terminal discards a cancelled APC or OSC. Its command does not run and it is not passed to the unknown sequence callback. For example, ESC _ G a=t,i=7;AAAA followed by CAN stores no image. |
| GHOSTTY_TERMINAL_STRING_END_ABORTED | Another 8-bit control byte cut the string short. Most of these return the stream to ground. CSI (0x9B) starts a CSI sequence instead. The introducers DCS (0x90), OSC (0x9D), APC (0x9F), SOS (0x98) and PM (0x9E) start a new string on the same byte, which the stop reports with a START flag as well. See GhosttyTerminalWriteStop.reached. Inside an OSC, and inside a DCS once its header is complete, 8-bit bytes are content. So this is only reported for an APC or for a DCS still in its header. The terminal discards an aborted APC, just like a cancelled one. |
| GHOSTTY_TERMINAL_STRING_END_BEL | BEL (0x07) terminated the string. Only an OSC ends this way. |
Definition at line 310 of file terminal.h.
How a control string started.
Definition at line 285 of file terminal.h.
The kind of control string that started or ended.
| Enumerator | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| GHOSTTY_TERMINAL_STRING_KIND_APC | An APC, SOS or PM string. GhosttyTerminalWriteStop.byte at the start of the string tells you which one it is:
| ||||||||
| GHOSTTY_TERMINAL_STRING_KIND_DCS | A DCS string, started by P (0x50) after ESC or by 0x90. | ||||||||
| GHOSTTY_TERMINAL_STRING_KIND_OSC | An OSC string, started by ] (0x5D) after ESC or by 0x9D. | ||||||||
Definition at line 259 of file terminal.h.
| GHOSTTY_API GhosttyResult ghostty_terminal_compress | ( | GhosttyTerminal | terminal, |
| GhosttyTerminalCompressionMode | mode, | ||
| GhosttyTerminalCompressionResult * | out_result ) |
Compress eligible terminal scrollback.
Incremental mode performs bounded work suitable for an idle callback. A pending result means the application should invoke another step while the terminal remains idle. A complete result means no continuation is needed until ghostty_terminal_compression_activity() changes. Full mode performs one synchronous scan and can stall on large scrollback buffers.
Compression is opportunistic. Complete means the pass has finished, not that every page was compressed: pages may be unprofitable or encounter an allocation or reclamation failure. Compression changes only the terminal's storage representation and never its logical contents or scrollback limit. Accessing compressed history restores it transparently.
This function is not thread-safe with other operations on the same terminal. You must serialize it with writes, rendering, searches, and other terminal access.
| terminal | The terminal handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| mode | The amount of compression work to perform | |
| [out] | out_result | Receives the compression scheduling result |
| GHOSTTY_API GhosttyResult ghostty_terminal_compression_activity | ( | GhosttyTerminal | terminal, |
| uint64_t * | out_activity ) |
Return the current compression activity token.
The token is opaque and only equality comparisons are meaningful. An embedding application should cache it and restart its compression idle delay whenever the value changes. The value may wrap and changes in either direction have the same meaning.
This function only observes terminal state. It does not perform or schedule compression.
| terminal | The terminal handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| [out] | out_activity | Receives the current activity token |
| GHOSTTY_API GhosttyResult ghostty_terminal_continuation_alloc | ( | GhosttyTerminal | terminal, |
| const GhosttyAllocator * | allocator, | ||
| uint8_t ** | out_ptr, | ||
| size_t * | out_len ) |
Return an allocated copy of the terminal's replay-safe VT continuation.
The returned bytes are allocated with allocator, or the default allocator when allocator is NULL. You must release them with ghostty_free(), passing the same allocator and returned length. An empty continuation is a successful result with *out_ptr set to NULL and *out_len set to zero, which can also be passed to ghostty_free(). Continuation tracking must have been enabled by setting GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES to a nonzero value before the input that produced the continuation was written.
You must serialize this operation with all other access to the same terminal.
| terminal | Terminal to read from (must not be NULL) | |
| allocator | Allocator for the output, or NULL for the default allocator | |
| [out] | out_ptr | Allocated continuation bytes (must not be NULL) |
| [out] | out_len | Number of continuation bytes (must not be NULL) |
| GHOSTTY_API GhosttyResult ghostty_terminal_continuation_buf | ( | GhosttyTerminal | terminal, |
| uint8_t * | buf, | ||
| size_t | buf_len, | ||
| size_t * | out_written ) |
Copy the terminal's replay-safe VT continuation into a caller buffer.
If buf is too small, this returns GHOSTTY_OUT_OF_SPACE and sets out_written to the size needed. To get the size first, pass NULL for buf and 0 for buf_len. When no escape sequence or UTF-8 character is left unfinished, the continuation is empty and needs no space, so this returns GHOSTTY_SUCCESS with out_written set to 0, even for a size query.
Continuation tracking must have been enabled by setting GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES to a nonzero value before the input that produced the continuation was written.
You must serialize this operation with all other access to the same terminal.
| terminal | Terminal to read from (must not be NULL) | |
| buf | Buffer to write the continuation into. May be NULL if buf_len is 0. | |
| buf_len | Size of buf in bytes | |
| [out] | out_written | The number of bytes written, or the size needed if the result is GHOSTTY_OUT_OF_SPACE. Must not be NULL. |
buf, or GHOSTTY_INVALID_VALUE if an argument is invalid, tracking is disabled, or the current continuation is unavailable | GHOSTTY_API GhosttyResult ghostty_terminal_continuation_write | ( | GhosttyTerminal | terminal, |
| GhosttyWriter | writer ) |
Write the terminal's replay-safe VT continuation to a callback writer.
The continuation is the exact byte suffix needed to reconstruct unfinished VT parser or UTF-8 decoder state in an equivalent terminal. It is empty when the stream is at ground. The callback is invoked synchronously and may be called more than once. It must not call terminal APIs with the same terminal handle.
Continuation tracking must have been enabled by setting GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES to a nonzero value before the input that produced the continuation was written.
You must serialize this operation with both VT write functions and all other access to the same terminal.
| terminal | Terminal to read from (must not be NULL) |
| writer | Destination writer whose write callback must not be NULL |
| 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.
| terminal | The terminal handle to free (may be NULL) |
| 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.
| 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) |
| 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.
Use this when each call into the library is expensive, for example from WebAssembly or from another language through its foreign function interface. It reads every key in one call. From C in the same process it costs the same as calling ghostty_terminal_get() once per key, so use whichever reads better.
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).
| 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) |
| 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 Cells and Rows 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.
| 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) |
| 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.
| terminal | Terminal instance. | |
| point | Point to track. | |
| [out] | out_ref | On success, receives the tracked reference handle. |
| GHOSTTY_API GhosttyResult ghostty_terminal_new | ( | const GhosttyAllocator * | allocator, |
| GhosttyTerminal * | terminal, | ||
| uint16_t | cols, | ||
| uint16_t | rows ) |
Create a new terminal instance.
The terminal starts with various reasonable defaults e.g. around scrollback limits. Use ghostty_terminal_set() to change any options prior to using the terminal.
| allocator | Pointer to allocator, or NULL to use the default allocator |
| terminal | Pointer to store the created terminal handle |
| cols | Terminal width in cells (must be greater than zero) |
| rows | Terminal height in cells (must be greater than zero) |
| 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.
| 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) |
| 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.
If synchronized output was enabled, the GHOSTTY_TERMINAL_OPT_RENDER_HOLD callback is invoked to report that the hold ended.
| terminal | The terminal handle (may be NULL, in which case this is a no-op) |
| 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, the grid is left as is, but everything below still applies.
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.
If synchronized output was enabled, the GHOSTTY_TERMINAL_OPT_RENDER_HOLD callback is invoked to report that the hold ended.
| 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 |
| GHOSTTY_API GhosttyResult 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_TERMINAL_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_TERMINAL_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). When using GHOSTTY_TERMINAL_SCROLL_VIEWPORT_DELTA_PROMPT, set delta_prompt to the signed number of prompts to move. See GHOSTTY_TERMINAL_SCROLL_VIEWPORT_DELTA_PROMPT for the navigation behavior. For other behaviors, the value is ignored.
| terminal | The terminal handle (NULL returns GHOSTTY_INVALID_VALUE) |
| behavior | The scroll behavior as a tagged union |
| 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*).
Passing NULL for value restores the option's default, the same value a new terminal starts with. Each GhosttyTerminalOption value documents its default. Callbacks and the userdata pointer default to NULL, so passing NULL removes them. GHOSTTY_TERMINAL_OPT_MODE and GHOSTTY_TERMINAL_OPT_MODE_DEFAULT have no default to restore, so they return GHOSTTY_INVALID_VALUE for NULL.
Callbacks are invoked synchronously during VT writes. Callbacks must not call ghostty_terminal_vt_write() or ghostty_terminal_vt_write_until() on the same terminal. The terminal is not reentrant, and nothing checks for this or reports an error. The bytes go into the parser in the middle of the sequence that called you, so they can be lost or make that sequence run a second time. See The rules for callbacks.
| terminal | The terminal handle, must not be NULL |
| option | The option to set |
| value | Pointer to the value to set (type depends on the option), or NULL to restore the option's default |
| 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.
| terminal | The terminal handle |
| data | Pointer to the data to write |
| len | Length of the data in bytes |
| GHOSTTY_API GhosttyResult ghostty_terminal_vt_write_until | ( | GhosttyTerminal | terminal, |
| const uint8_t * | data, | ||
| size_t | len, | ||
| uint32_t | boundaries, | ||
| GhosttyTerminalWriteStop * | out ) |
Write VT-encoded data to the terminal, stopping right after the first byte that reaches one of the requested boundaries.
This works like ghostty_terminal_vt_write(), but it can pause at points you care about. It tells you exactly where a control string starts or ends, using the same parse that updates the terminal. For example, a program that sits between a shell and a terminal can use it to:
Pass the boundaries to stop at as GhosttyTerminalBoundary flags. The call consumes input up to and including the first byte that reaches one of them, and reports that point in out. The terminal only processes the consumed bytes, and callbacks only run for those bytes. Pass the remaining bytes in your next call.
Every byte you pass is eventually consumed in order, so the terminal ends up in the same state as if you had called ghostty_terminal_vt_write() with all of it.
See Stopping a write at a string boundary for how to find string content, the cases that need care, and waiting for ground.
| terminal | The terminal handle (must not be NULL) | |
| data | Pointer to the data to write, or NULL when len is zero | |
| len | Length of the data in bytes | |
| boundaries | GhosttyTerminalBoundary flags to stop at. Must be nonzero and contain only defined flags. | |
| [out] | out | Where the call stopped. Must not be NULL, and its size must be set with GHOSTTY_INIT_SIZED(). |
1.17.0