From c1e616c6cda402c6823d97dba89dde690808f2b7 Mon Sep 17 00:00:00 2001 From: Alessandro De Blasis Date: Mon, 23 Mar 2026 16:54:05 +0100 Subject: [PATCH] libghostty: add ghostty_free for cross-runtime memory safety On Windows, Zig's built-in libc and MSVC's CRT maintain separate heaps, so calling free() on memory allocated by the library causes undefined behavior. Add ghostty_free() that frees through the same allocator that performed the allocation, making it safe on all platforms. Update format_alloc docs and all examples to use ghostty_free() instead of free(). Co-Authored-By: Claude Opus 4.6 (1M context) --- example/c-vt-cmake-static/src/main.c | 2 +- example/c-vt-cmake/src/main.c | 2 +- example/c-vt-formatter/src/main.c | 2 +- include/ghostty/vt/allocator.h | 25 +++++++++++++++++++++++++ include/ghostty/vt/formatter.h | 7 +++---- src/lib_vt.zig | 1 + src/terminal/c/main.zig | 18 ++++++++++++++++++ 7 files changed, 50 insertions(+), 7 deletions(-) diff --git a/example/c-vt-cmake-static/src/main.c b/example/c-vt-cmake-static/src/main.c index 4821e727e..233bd34d1 100644 --- a/example/c-vt-cmake-static/src/main.c +++ b/example/c-vt-cmake-static/src/main.c @@ -45,7 +45,7 @@ int main() { fwrite(buf, 1, len, stdout); printf("\n"); - free(buf); + ghostty_free(NULL, buf, len); ghostty_formatter_free(formatter); ghostty_terminal_free(terminal); return 0; diff --git a/example/c-vt-cmake/src/main.c b/example/c-vt-cmake/src/main.c index 389be5936..992586451 100644 --- a/example/c-vt-cmake/src/main.c +++ b/example/c-vt-cmake/src/main.c @@ -45,7 +45,7 @@ int main() { fwrite(buf, 1, len, stdout); printf("\n"); - free(buf); + ghostty_free(NULL, buf, len); ghostty_formatter_free(formatter); ghostty_terminal_free(terminal); return 0; diff --git a/example/c-vt-formatter/src/main.c b/example/c-vt-formatter/src/main.c index 5d408b172..56f9d1220 100644 --- a/example/c-vt-formatter/src/main.c +++ b/example/c-vt-formatter/src/main.c @@ -56,7 +56,7 @@ int main() { printf("\n"); // Clean up - free(buf); + ghostty_free(NULL, buf, len); ghostty_formatter_free(formatter); ghostty_terminal_free(terminal); return 0; diff --git a/include/ghostty/vt/allocator.h b/include/ghostty/vt/allocator.h index 4cebe91bb..f1406cf79 100644 --- a/include/ghostty/vt/allocator.h +++ b/include/ghostty/vt/allocator.h @@ -191,6 +191,31 @@ typedef struct GhosttyAllocator { const GhosttyAllocatorVtable *vtable; } GhosttyAllocator; +/** + * 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. + * + * @param allocator Pointer to the allocator that was used to allocate the + * memory, or NULL if the default allocator was used + * @param ptr Pointer to the memory to free (may be NULL) + * @param len Length of the allocation in bytes (must match the original + * allocation size) + * + * @ingroup allocator + */ +void ghostty_free(const GhosttyAllocator* allocator, uint8_t* ptr, size_t len); + /** @} */ #endif /* GHOSTTY_VT_ALLOCATOR_H */ diff --git a/include/ghostty/vt/formatter.h b/include/ghostty/vt/formatter.h index 4beb5fc77..5a9bb524b 100644 --- a/include/ghostty/vt/formatter.h +++ b/include/ghostty/vt/formatter.h @@ -186,10 +186,9 @@ GhosttyResult ghostty_formatter_format_buf(GhosttyFormatter formatter, * * Each call formats the current terminal state. The buffer is allocated * using the provided allocator (or the default allocator if NULL). - * The caller is responsible for freeing the returned buffer. When using - * the default allocator (NULL), the buffer can be freed with `free()`. - * When using a custom allocator, the buffer must be freed using the - * same allocator. + * The caller is responsible for freeing the returned buffer with + * ghostty_free(), passing the same allocator (or NULL for the default) + * that was used for the allocation. * * @param formatter The formatter handle (must not be NULL) * @param allocator Pointer to allocator, or NULL to use the default allocator diff --git a/src/lib_vt.zig b/src/lib_vt.zig index 7a75bb92a..2816befae 100644 --- a/src/lib_vt.zig +++ b/src/lib_vt.zig @@ -218,6 +218,7 @@ comptime { @export(&c.grid_ref_graphemes, .{ .name = "ghostty_grid_ref_graphemes" }); @export(&c.grid_ref_style, .{ .name = "ghostty_grid_ref_style" }); @export(&c.build_info, .{ .name = "ghostty_build_info" }); + @export(&c.free_alloc, .{ .name = "ghostty_free" }); // On Wasm we need to export our allocator convenience functions. if (builtin.target.cpu.arch.isWasm()) { diff --git a/src/terminal/c/main.zig b/src/terminal/c/main.zig index 11e14f8c7..b1a87e452 100644 --- a/src/terminal/c/main.zig +++ b/src/terminal/c/main.zig @@ -1,3 +1,6 @@ +const lib_alloc = @import("../../lib/allocator.zig"); +const CAllocator = lib_alloc.Allocator; + const buildpkg = @import("build_info.zig"); pub const cell = @import("cell.zig"); pub const color = @import("color.zig"); @@ -112,6 +115,21 @@ pub const mouse_encoder_encode = mouse_encode.encode; pub const paste_is_safe = paste.is_safe; +/// Free memory that was allocated by a libghostty-vt function. +/// +/// This must be used to free buffers returned by functions like +/// `format_alloc`. Pass the same allocator (or NULL for the default) +/// that was used for the allocation. +pub fn free_alloc( + alloc_: ?*const CAllocator, + ptr: ?[*]u8, + len: usize, +) callconv(.c) void { + const mem = ptr orelse return; + const alloc = lib_alloc.default(alloc_); + alloc.free(mem[0..len]); +} + pub const size_report_encode = size_report.encode; pub const cell_get = cell.get;