System Interface

Detailed Description

Runtime-swappable function pointers for operations that depend on external implementations (e.g. image decoding).

These are process-global settings that must be configured at startup before any terminal functionality that depends on them is used. Setting these enables various optional features of the terminal. For example, setting a PNG decoder enables PNG image support in the Kitty Graphics Protocol.

Use ghostty_sys_set() with a GhosttySysOption to install or clear an implementation. Passing NULL as the value clears the implementation and disables the corresponding feature.

Example

Defining a PNG decode callback

bool decode_png(void* userdata,
                const GhosttyAllocator* allocator,
                const uint8_t* data,
                size_t data_len,
                GhosttySysImage* out) {
  int* count = (int*)userdata;
  (*count)++;
  printf("  decode_png called (size=%zu, call #%d)\n", data_len, *count);
 
  /* Allocate RGBA pixel data through the provided allocator. */
  const size_t pixel_len = 4;  /* 1x1 RGBA */
  uint8_t* pixels = ghostty_alloc(allocator, pixel_len);
  if (!pixels) return false;
 
  /* Fill with red (R=255, G=0, B=0, A=255). */
  pixels[0] = 255;
  pixels[1] = 0;
  pixels[2] = 0;
  pixels[3] = 255;
 
  out->width = 1;
  out->height = 1;
  out->data = pixels;
  out->data_len = pixel_len;
  return true;
}

Installing the callback and sending a PNG image

int main() {
  /* Install the PNG decoder via the sys interface. */
  int decode_count = 0;
  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
 
  /* Create a terminal with Kitty graphics enabled. */
  GhosttyTerminal terminal = NULL;
  if (ghostty_terminal_new(NULL, &terminal, 80, 24) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create terminal\n");
    return 1;
  }
 
  /* Set the cell size in pixels. Image sizes depend on it. */
  ghostty_terminal_resize(terminal, 80, 24, 8, 16);
 
  /* Set a storage limit to enable Kitty graphics. */
  uint64_t storage_limit = 64 * 1024 * 1024;  /* 64 MiB */
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
                       &storage_limit);
 
  /* Install write_pty to see the protocol response. */
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
                       (const void*)on_write_pty);
 
  /* Move the cursor to row 10 so the images have room to scroll up. */
  const char* move = "\x1b[10;1H";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)move, strlen(move));
 
  /*
   * Send a 1x1 PNG image and place it at the cursor. The image is
   * attached to that cell, so it moves when the text moves.
   *
   * The escape sequence is:
   *   ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
   *
   * Where:
   *   a=T    transmit the image and place it
   *   f=100  the data is a PNG
   *   q=1    only reply on errors (q=0 would also reply on success)
   */
  printf("Sending Kitty graphics PNG image:\n");
  const char* kitty_cmd =
    "\x1b_Ga=T,f=100,q=1;"
    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
    "DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
    "\x1b\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
                            strlen(kitty_cmd));
 
  printf("PNG decode calls: %d\n", decode_count);
 
  /*
   * Show a second image with placeholder cells. First send a green 1x1
   * image with ID 3 and give it a virtual placement 2 columns wide and
   * 1 row tall (U=1). Then, on the next row, print two placeholder
   * characters (U+10EEEE) where the image should appear:
   *
   *   ESC[38;5;3m    the foreground color says which image: ID 3
   *   U+0305 U+0305  the first cell shows row 0, column 0 of the image
   *   U+0305 U+030D  the second cell shows row 0, column 1
   *
   * The image moves with those cells, like text.
   */
  const char* placeholder_cmds =
    "\x1b_Ga=T,U=1,f=32,i=3,s=1,v=1,c=2,r=1,q=2;AP8A/w==\x1b\\"
    "\r\n\x1b[38;5;3m"
    "\xf4\x8e\xbb\xae\xcc\x85\xcc\x85"
    "\xf4\x8e\xbb\xae\xcc\x85\xcc\x8d"
    "\x1b[39m";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)placeholder_cmds,
                            strlen(placeholder_cmds));
 
  /*
   * The storage has a generation of its own. It changes when a program
   * sends, places or deletes an image, but not when images only move on
   * screen. That is why the frames below use the render state's
   * placements generation to know when to read the list again.
   */
  GhosttyKittyGraphics graphics = NULL;
  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
    fprintf(stderr, "Failed to get kitty graphics storage\n");
    return 1;
  }
  uint64_t storage_generation = 0;
  ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
                             &storage_generation);
  printf("\nStorage generation: %llu\n",
         (unsigned long long)storage_generation);
 
  /* Find what to draw from the render state, over three frames. */
  if (run_frames(terminal) != 0) return 1;
 
  /* Animate a second image by driving the animation tick. */
  printf("\nPlaying an animation:\n");
  if (run_animation(terminal) != 0) return 1;
 
  /* Clean up. */
  ghostty_terminal_free(terminal);
 
  /* Clear the sys callbacks. */
  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, NULL);
  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, NULL);
 
  return 0;
}

Typedefs
typedef void(*)	GhosttySysLogFn(void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)
typedef bool(*)	GhosttySysDecodePngFn(void *userdata, const GhosttyAllocator *allocator, const uint8_t *data, size_t data_len, GhosttySysImage *out)
typedef bool(*)	GhosttySysRandomSecureFn(void *userdata, uint8_t *buf, size_t len)

Enumerations
enum	GhosttySysLogLevel
enum	GhosttySysOption { GHOSTTY_SYS_OPT_USERDATA = 0 , GHOSTTY_SYS_OPT_DECODE_PNG = 1 , GHOSTTY_SYS_OPT_LOG = 2 , GHOSTTY_SYS_OPT_RANDOM_SECURE = 3 , GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_sys_set (GhosttySysOption option, const void *value)
GHOSTTY_API void	ghostty_sys_log_stderr (void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)

Data Structures
struct	GhosttySysImage

Typedef Documentation

GhosttySysDecodePngFn

typedef bool(*) GhosttySysDecodePngFn(void *userdata, const GhosttyAllocator *allocator, const uint8_t *data, size_t data_len, GhosttySysImage *out)

Callback type for PNG decoding.

The library calls this when it receives a PNG image and needs the raw pixels. The callback decodes the PNG bytes in data and describes the result in out. See the example in the System Interface overview for a complete callback.

On success

Allocate the pixel buffer with ghostty_alloc() and allocator, write the decoded pixels into it, set all four fields of out, and return true. The library then owns the buffer and frees it with the same allocator. See GhosttySysImage for the expected pixel layout.

The allocator limits how much memory a single image may use, so ghostty_alloc() can return NULL for very large images. Treat that as a failure.

On failure

Free anything that was allocated and return false. The library does not read out in this case, and the image is rejected.

The output struct starts zeroed

The library sets every field of out to zero before it calls the callback. This has two practical effects:

• If the callback returns true but data is still NULL, the library treats the call as a failure.
• Language bindings can store a pointer into out directly. Some runtimes, such as Go, require memory to be initialized before a pointer is written into it, and this guarantee satisfies that requirement.

Only out is zeroed. Memory returned by ghostty_alloc() is not.

data and allocator are only valid for the duration of the callback.

Parameters

	userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
	allocator	The allocator to use for the output pixel buffer
	data	Pointer to the raw PNG data
	data_len	Length of the raw PNG data in bytes
[out]	out	The decoded image. Zeroed by the library before the call, and filled in by the callback on success.

Returns

true if the image was decoded and out was filled in, false on failure

Definition at line 168 of file sys.h.

GhosttySysLogFn

typedef void(*) GhosttySysLogFn(void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)

Callback type for logging.

When installed, internal library log messages are delivered through this callback instead of being discarded. The embedder is responsible for formatting and routing log output.

scope is the log scope name as UTF-8 bytes (e.g. "osc", "kitty"). When the log is unscoped (default scope), scope_len is 0.

All pointer arguments are only valid for the duration of the callback. The callback must be safe to call from any thread.

Parameters

userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
level	The severity level of the log message
scope	Pointer to the scope name bytes
scope_len	Length of the scope name in bytes
message	Pointer to the log message bytes
message_len	Length of the log message in bytes

Definition at line 110 of file sys.h.

GhosttySysRandomSecureFn

typedef bool(*) GhosttySysRandomSecureFn(void *userdata, uint8_t *buf, size_t len)

Callback type for secure random bytes.

Fills buf with len cryptographically secure random bytes. The library uses this for secrets, so it must be a real CSPRNG (getrandom, arc4random_buf, BCryptGenRandom, crypto.getRandomValues, ...); a predictable source is a security hole.

Parameters

userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
buf	Buffer to fill
len	Number of bytes to fill

Returns

true if the buffer was filled, false if no entropy is available

Definition at line 188 of file sys.h.

Enumeration Type Documentation

GhosttySysLogLevel

enum GhosttySysLogLevel

Log severity levels for the log callback.

Definition at line 82 of file sys.h.

GhosttySysOption

enum GhosttySysOption

System option identifiers for ghostty_sys_set().

Enumerator
GHOSTTY_SYS_OPT_USERDATA	Set the userdata pointer passed to all sys callbacks. Input type: void* (or NULL)
GHOSTTY_SYS_OPT_DECODE_PNG	Set the PNG decode function. When set, the terminal can accept PNG images via the Kitty Graphics Protocol. When cleared (NULL value), PNG decoding is unsupported and PNG image data will be rejected. Input type: GhosttySysDecodePngFn (function pointer, or NULL)
GHOSTTY_SYS_OPT_LOG	Set the log callback. When set, internal library log messages are delivered to this callback. When cleared (NULL value), log messages are silently discarded. Use ghostty_sys_log_stderr as a convenience callback that writes formatted messages to stderr. Which log levels are emitted depends on the build mode of the library and is not configurable at runtime. Debug builds emit all levels (debug and above). Release builds emit info and above; debug-level messages are compiled out entirely and will never reach the callback. Input type: GhosttySysLogFn (function pointer, or NULL)
GHOSTTY_SYS_OPT_RANDOM_SECURE	Override the secure random source. By default the library draws secure random bytes from the platform (getrandom or arc4random_buf on POSIX, CNG on Windows). Targets without one, such as wasm32-freestanding, have no default and operations that need entropy fail with GHOSTTY_IO_ERROR until this is set. When set, it is used instead of the platform source on every target. When cleared (NULL value), the platform default is restored. Input type: GhosttySysRandomSecureFn (function pointer, or NULL)

Definition at line 196 of file sys.h.

Function Documentation

ghostty_sys_log_stderr()

GHOSTTY_API void ghostty_sys_log_stderr	(	void *	userdata,
		GhosttySysLogLevel	level,
		const uint8_t *	scope,
		size_t	scope_len,
		const uint8_t *	message,
		size_t	message_len )

Built-in log callback that writes to stderr.

Formats each message as "[level](scope): message\n". Can be passed directly to ghostty_sys_set():

ghostty_sys_set(GHOSTTY_SYS_OPT_LOG, &ghostty_sys_log_stderr);

References ghostty_sys_log_stderr().

Referenced by ghostty_sys_log_stderr().

ghostty_sys_set()

GHOSTTY_API GhosttyResult ghostty_sys_set	(	GhosttySysOption	option,
		const void *	value )

Set a system-level option.

Configures a process-global implementation function. These should be set once at startup before using any terminal functionality that depends on them.

Parameters

option	The option to set
value	Pointer to the value (type depends on the option), or NULL to clear it

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the option is not recognized

Examples

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

References ghostty_sys_set().

Referenced by ghostty_sys_set().