Allocators

Run the library on your own memory allocator. More...

Detailed Description

Run the library on your own memory allocator.

An allocator is the set of functions libghostty-vt calls to get and free memory.

Most programs never need this. Any function that takes a const GhosttyAllocator* accepts NULL, which selects the default allocator. You only need your own to run the library on memory you control.

Example

  Stats stats = {0};
  GhosttyAllocator allocator = {
      .ctx = &stats,
      .vtable = &my_vtable,
  };
 
  /* The terminal keeps a pointer to the allocator, so `allocator` must
   * stay alive until ghostty_terminal_free(). */
  GhosttyTerminal terminal;
  if (ghostty_terminal_new(&allocator, &terminal, 80, 24) !=
      GHOSTTY_SUCCESS) {
    fprintf(stderr, "ghostty_terminal_new failed\n");
    return 1;
  }

Full program: c-vt-allocator/src/main.c

See Memory for what the default is, how to write your own allocator, and how to free memory the library gives you.

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

allocator	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 len is zero or 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.

Use this instead of the C free(), which can use a different heap than the library. See Allocating and Freeing Buffers for why.

Passing a NULL ptr does nothing.

Parameters

allocator	Pointer to the allocator that was used to allocate the memory, or NULL if the default allocator was used
ptr	Pointer to the memory to free (may be NULL)
len	Length of the allocation in bytes (must match the original allocation size)

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, c-vt-snapshot/src/main.c, and c-vt-stream/src/main.c.