#include <limits.h>
#include <stddef.h>
#include <stdint.h>

Data Structures
struct	GhosttyString
struct	GhosttyBuffer
struct	GhosttySurfacePosition
struct	GhosttyCodepoints

Macros
#define	GHOSTTY_ENUM_TYPED
#define	GHOSTTY_INIT_SIZED(type)

Typedefs
typedef struct GhosttyTerminalImpl *	GhosttyTerminal
typedef struct GhosttySnapshotDecoderImpl *	GhosttySnapshotDecoder
typedef struct GhosttyTrackedGridRefImpl *	GhosttyTrackedGridRef
typedef struct GhosttyKittyGraphicsImpl *	GhosttyKittyGraphics
typedef const struct GhosttyKittyGraphicsImageImpl *	GhosttyKittyGraphicsImage
typedef struct GhosttyKittyGraphicsPlacementIteratorImpl *	GhosttyKittyGraphicsPlacementIterator
typedef struct GhosttyRenderStateImpl *	GhosttyRenderState
typedef struct GhosttyRenderStateRowIteratorImpl *	GhosttyRenderStateRowIterator
typedef struct GhosttyRenderStateRowCellsImpl *	GhosttyRenderStateRowCells
typedef struct GhosttySearchImpl *	GhosttySearch
typedef struct GhosttySgrParserImpl *	GhosttySgrParser
typedef struct GhosttyFormatterImpl *	GhosttyFormatter
typedef struct GhosttyOscParserImpl *	GhosttyOscParser
typedef struct GhosttyOscCommandImpl *	GhosttyOscCommand

Enumerations
enum	GhosttyResult { GHOSTTY_SUCCESS = 0 , GHOSTTY_OUT_OF_MEMORY = -1 , GHOSTTY_INVALID_VALUE = -2 , GHOSTTY_OUT_OF_SPACE = -3 , GHOSTTY_NO_VALUE = -4 , GHOSTTY_IO_ERROR = -5 , GHOSTTY_LIMIT_EXCEEDED = -6 , GHOSTTY_REJECTED = -7 , GHOSTTY_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyFormatterFormat { GHOSTTY_FORMATTER_FORMAT_PLAIN , GHOSTTY_FORMATTER_FORMAT_VT , GHOSTTY_FORMATTER_FORMAT_HTML , GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API const char *	ghostty_type_json (void)

Detailed Description

Common types, macros, and utilities for libghostty-vt.

Definition in file types.h.

Macro Definition Documentation

◆ GHOSTTY_ENUM_TYPED

#define GHOSTTY_ENUM_TYPED

Enum int-sizing helpers.

The Zig side backs all C enums with c_int, so the C declarations must use int as their underlying type to maintain ABI compatibility.

C++11 and C23 support explicit enum underlying types with enum : int { ... }. Clang and GCC 13+ also support this syntax as an extension in older C language modes, so use it when available.

Other pre-C23 C compilers are free to choose any type that can represent all values (C11 §6.7.2.2). For those compilers, we add an INT_MAX sentinel as the last entry so the compatible type must be able to represent INT_MAX. The exact compatible type and its signedness remain implementation-defined in this fallback.

INT_MAX is used rather than a fixed constant like 0xFFFFFFFF because enum constants must have type int in pre-C23 C. Values above INT_MAX are a constraint violation there; compilers that accept them may interpret them as negative values via two's complement, which can collide with legitimate negative enum values.

Usage:

typedef enum GHOSTTY_ENUM_TYPED {
    FOO_A = 0,
    FOO_B = 1,
    FOO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} Foo;

Definition at line 81 of file types.h.

◆ GHOSTTY_INIT_SIZED

#define GHOSTTY_INIT_SIZED ( type )

Value:

((type){ .size = sizeof(type) })

Initialize a sized struct to zero and set its size field.

Sized structs use a size field as the first member for ABI compatibility. This macro zero-initializes the struct and sets the size field to sizeof(type), which allows the library to detect which version of the struct the caller was compiled against.

Parameters

type	The struct type to initialize

Returns: A zero-initialized struct with the size field set

Example:

GhosttyFormatterTerminalOptions opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
opts.trim = true;

Examples: c-vt-formatter/src/main.c, c-vt-grid-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-search/src/main.c, and c-vt-selection-gesture/src/main.c.

Definition at line 349 of file types.h.

Enumeration Type Documentation

◆ GhosttyResult

enum GhosttyResult

Result codes for libghostty-vt operations.

Enumerator
GHOSTTY_SUCCESS	Operation completed successfully
GHOSTTY_OUT_OF_MEMORY	Operation failed due to failed allocation
GHOSTTY_INVALID_VALUE	Operation failed due to invalid value
GHOSTTY_OUT_OF_SPACE	Operation failed because the provided buffer was too small
GHOSTTY_NO_VALUE	The requested value has no value
GHOSTTY_IO_ERROR	Operation failed while reading from or writing to external I/O
GHOSTTY_LIMIT_EXCEEDED	Operation failed because encoded input exceeded a configured limit
GHOSTTY_REJECTED	Operation was rejected by a safety check (e.g. pasted text that could inject commands). Nothing was done. Confirm with the user and retry with the operation's allow flag set.

Examples: c-vt-compression/src/main.c, c-vt-encode-key/src/main.c, c-vt-encode-mouse/src/main.c, c-vt-formatter/src/main.c, c-vt-grid-ref-tracked/src/main.c, c-vt-grid-traverse/src/main.c, c-vt-paste/src/main.c, c-vt-search/src/main.c, c-vt-selection-gesture/src/main.c, and c-vt-sgr/src/main.c.

Definition at line 88 of file types.h.

Function Documentation

◆ ghostty_type_json()

GHOSTTY_API const char * ghostty_type_json ( void )

Return the versioned libghostty-vt C type manifest for the current target.

The manifest defines all the public types available in the linked build. The types contain their layouts, enum values, union fields, and more.

Language bindings, such as WebAssembly hosts, should obtain offsets, sizes, alignments, array shapes, enum constants, and tagged-union arms from this manifest rather than hardcoding them. Consumers should reject unknown schema versions and verify the descriptors they require at initialization.

Packed type descriptors define fields using lsb and width. lsb is relative to bit zero of the containing numerical value; for nested packed layouts it is relative to the immediate containing field. Tagged packed unions select an inline arm layout using the named tag field. These layouts describe the current linked build and are not a cross-version stability promise.

The formal format is defined by the libghostty-vt ABI manifest JSON Schema.

Example (abbreviated):

{
  "schema": 1,
  "abi": {
    "target": "wasm32", "os": "freestanding", "environment": "none",
    "pointer_size": 4, "usize_size": 4, "max_alignment": 16,
    "endian": "little"
  },
  "types": {
    "GhosttyRenderStateData": {
      "kind": "enum", "size": 4, "align": 4,
      "underlying": "i32", "prefix": "GHOSTTY_RENDER_STATE_DATA_",
      "values": { "INVALID": 0, "DIRTY": 3, "MAX_VALUE": 2147483647 }
    },
    "GhosttyStyleColor": {
      "kind": "struct", "size": 16, "align": 8,
      "fields": {
        "tag": { "offset": 0, "size": 4,
                 "type": "GhosttyStyleColorTag" },
        "value": { "offset": 8, "size": 8,
                   "type": "GhosttyStyleColorValue", "tag": "tag",
                   "arms": { "NONE": null, "PALETTE": "palette",
                             "RGB": "rgb" } }
      }
    }
  }
}

The returned pointer is valid for the lifetime of the process.

Returns: Pointer to the null-terminated JSON string.

References ghostty_type_json().

Referenced by ghostty_type_json().

Data Structures

Macros

Typedefs

Enumerations

Functions