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.

Typedefs
typedef struct GhosttyTerminal *	GhosttyTerminal

Enumerations
enum	GhosttyTerminalScrollViewportTag { GHOSTTY_SCROLL_VIEWPORT_TOP , GHOSTTY_SCROLL_VIEWPORT_BOTTOM , GHOSTTY_SCROLL_VIEWPORT_DELTA }

Functions
GhosttyResult	ghostty_terminal_new (const GhosttyAllocator *allocator, GhosttyTerminal *terminal, GhosttyTerminalOptions options)
void	ghostty_terminal_free (GhosttyTerminal terminal)
void	ghostty_terminal_reset (GhosttyTerminal terminal)
GhosttyResult	ghostty_terminal_resize (GhosttyTerminal terminal, uint16_t cols, uint16_t rows)
void	ghostty_terminal_vt_write (GhosttyTerminal terminal, const uint8_t *data, size_t len)
void	ghostty_terminal_scroll_viewport (GhosttyTerminal terminal, GhosttyTerminalScrollViewport behavior)

Data Structures
struct	GhosttyTerminalOptions
union	GhosttyTerminalScrollViewportValue
struct	GhosttyTerminalScrollViewport

Typedef Documentation

GhosttyTerminal

typedef struct GhosttyTerminal* GhosttyTerminal

Opaque handle to a terminal instance.

Examples

c-vt-formatter/src/main.c.

Definition at line 34 of file terminal.h.

Enumeration Type Documentation

GhosttyTerminalScrollViewportTag

enum GhosttyTerminalScrollViewportTag

Scroll viewport behavior tag.

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

Definition at line 61 of file terminal.h.

Function Documentation

ghostty_terminal_free()

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.

ghostty_terminal_new()

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.

ghostty_terminal_reset()

void ghostty_terminal_reset

(

GhosttyTerminal

terminal

)

Perform a full reset of the terminal (RIS).

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

Parameters

Terminal

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

ghostty_terminal_resize()

GhosttyResult ghostty_terminal_resize	(	GhosttyTerminal	terminal,
		uint16_t	cols,
		uint16_t	rows )

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.

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)

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

ghostty_terminal_scroll_viewport()

void ghostty_terminal_scroll_viewport	(	GhosttyTerminal	terminal,
		GhosttyTerminalScrollViewport	behavior )

Scroll the terminal viewport.

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

Parameters

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

ghostty_terminal_vt_write()

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. Only read-only sequences are processed; sequences that require output (queries) are ignored.

In the future, a callback-based API will be added to allow handling of output or side effect sequences.

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.