Detailed Description

libghostty-vt does require memory allocation for various operations, but is resilient to allocation failures and will gracefully handle out-of-memory situations by returning error codes.

The exact memory management semantics are documented in the relevant functions and data structures.

libghostty-vt uses explicit memory allocation via an allocator interface provided by GhosttyAllocator. The interface is based on the Zig allocator interface, since this has been shown to be a flexible and powerful interface in practice and enables a wide variety of allocation strategies.

For the common case, you can pass NULL as the allocator for any function that accepts one, and libghostty will use a default allocator. The default allocator will be libc malloc/free if libc is linked. Otherwise, a custom allocator is used (currently Zig's SMP allocator) that doesn't require any external dependencies.

Basic Usage

For simple use cases, you can ignore this interface entirely by passing NULL as the allocator parameter to functions that accept one. This will use the default allocator (typically libc malloc/free, if libc is linked, but we provide our own default allocator if libc isn't linked).

To use a custom allocator:

Implement the GhosttyAllocatorVtable function pointers
Create a GhosttyAllocator struct with your vtable and context
Pass the allocator to functions that accept one

Alloc/Free Helpers

ghostty_alloc() and ghostty_free() provide a simple malloc/free-style interface for allocating and freeing byte buffers through the library's allocator. These are useful when:

You need to allocate a buffer to pass into a libghostty-vt function (e.g. preparing input data for ghostty_terminal_vt_write()).
You need to free a buffer returned by a libghostty-vt function (e.g. the output of ghostty_formatter_format_alloc()).
You are on a platform where the library's internal allocator differs from the consumer's C runtime (e.g. Windows, where Zig's libc and MSVC's CRT maintain separate heaps), so calling the standard C free() on library-allocated memory would be undefined behavior.

Always use the same allocator (or NULL) for both the allocation and the corresponding free.

Functions
GHOSTTY_API uint8_t *	ghostty_alloc (const GhosttyAllocator *allocator, size_t len)
GHOSTTY_API void	ghostty_free (const GhosttyAllocator allocator, uint8_t ptr, size_t len)

Data Structures
struct	GhosttyAllocatorVtable
struct	GhosttyAllocator

Function Documentation

◆ ghostty_alloc()

GHOSTTY_API uint8_t * ghostty_alloc	(	const GhosttyAllocator *	allocator,
		size_t	len )

Allocate a buffer of len bytes.

Uses the provided allocator, or the default allocator if NULL is passed. The returned buffer must be freed with ghostty_free() using the same allocator.

Parameters

Memory Management	Pointer to the allocator to use, or NULL for the default
len	Number of bytes to allocate

Returns: Pointer to the allocated buffer, or NULL if allocation failed

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

◆ ghostty_free()

GHOSTTY_API void ghostty_free	(	const GhosttyAllocator *	allocator,
		uint8_t *	ptr,
		size_t	len )

Free memory that was allocated by a libghostty-vt function.

Use this to free buffers returned by functions such as ghostty_formatter_format_alloc(). Pass the same allocator that was used for the allocation, or NULL if the default allocator was used.

On platforms where the library's internal allocator differs from the consumer's C runtime (e.g. Windows, where Zig's libc and MSVC's CRT maintain separate heaps), calling the standard C free() on memory allocated by the library causes undefined behavior. This function guarantees the correct allocator is used regardless of platform.

It is safe to pass a NULL pointer; the call is a no-op in that case.