 |
libghostty-vt 0.0.0
|
|
libghostty-vt 0.0.0
|
The result codes, strings, and buffers that every API uses. More...
The result codes, strings, and buffers that every API uses.
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_UNSUPPORTED = -8 , GHOSTTY_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE } |
Functions | |
| GHOSTTY_API void | ghostty_sized_init (void *ptr, size_t size) |
| GHOSTTY_API const char * | ghostty_type_json (void) |
Macros | |
| #define | GHOSTTY_DEPRECATED(msg) |
| #define | GHOSTTY_ENUM_TYPED |
| #define | GHOSTTY_INIT_SIZED(type) |
Data Structures | |
| struct | GhosttyString |
| struct | GhosttyBuffer |
| struct | GhosttyCodepoints |
| struct | GhosttyCodepointBuffer |
| enum GhosttyResult |
Result codes for libghostty-vt operations.
Functions that can fail return one of these codes. GHOSTTY_SUCCESS is zero and every error is negative, so result < 0 tests for any error.
Functions that read or write values by key, such as ghostty_terminal_get(), return GHOSTTY_UNSUPPORTED for a key that this version of the library does not know. See Getting and Setting Values for how to use that to support older versions of the library. Functions of an optional feature that this build leaves out return it too. See Optional Features.
| Enumerator | |
|---|---|
| GHOSTTY_SUCCESS | Operation completed successfully |
| GHOSTTY_OUT_OF_MEMORY | Operation failed due to failed allocation |
| GHOSTTY_INVALID_VALUE | An argument is not valid. For example, a NULL pointer where a value is required, an enum value that is out of range, or a sized struct whose size is too small. When a key is involved, this means the library knows the key but a value passed with it is wrong. Compare GHOSTTY_UNSUPPORTED. |
| 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 person using your terminal and retry with the operation's allow flag set. |
| GHOSTTY_UNSUPPORTED | This library cannot do what was asked. Returned by the functions that read or write values by key when the key is newer than the library. Nothing is read or written. This usually means the program was built with a newer header than the library it is running with. Check for it to fall back gracefully, as shown in Newer Headers, Older Libraries. Also returned by every function of an optional feature that this build leaves out. For example, ghostty_snapshot_encode() returns it when the library was built without the snapshot feature. See Optional Features. |
| GHOSTTY_API void ghostty_sized_init | ( | void * | ptr, |
| size_t | size ) |
Initialize a sized struct at runtime.
This does the same thing as GHOSTTY_INIT_SIZED(). It sets every byte of the struct to zero and then stores size in the struct's size field. It is meant for language bindings that cannot use a C macro. Pass the size of the struct as your binding lays it out, which is sizeof of the struct in the header the binding was built from. See Sized Structs.
If ptr is NULL, or size is too small to hold the size field itself, this function does nothing.
| ptr | The struct to initialize, or NULL |
| size | The size of the struct in bytes |
| 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.
Every key enum also has a keys object. A key enum is the enum that a _get, _set or _get_multi function takes to pick a value, such as GhosttyTerminalData or GhosttyTerminalOption. Each key lists its direction and the type that its void * value points at:
Callback descriptors, such as GhosttyTerminalBellFn, describe a function pointer typedef. params lists the parameter types in order and return gives the return type. Both use the same type references as struct fields.
The formal format is defined by the libghostty-vt ABI manifest JSON Schema.
Example (abbreviated):
The returned pointer is valid for the lifetime of the process.
| #define GHOSTTY_DEPRECATED | ( | msg | ) |
Mark a function or type as deprecated.
A deprecated declaration still works, but it will be removed in a future major release. Code that uses it gets a compiler warning that includes msg, so the message should say what to use instead.
Put the macro before GHOSTTY_API on the declaration:
A program that calls ghostty_foo_create() then gets a warning like this one from GCC or Clang:
The macro uses __attribute__((deprecated)) on GCC and Clang and __declspec(deprecated) on MSVC. On other compilers it does nothing.
To turn the warnings off while you migrate, pass -Wno-deprecated-declarations to GCC or Clang. You can also define GHOSTTY_DEPRECATED yourself before including any libghostty-vt header, and the header keeps your definition:
| #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.
In C++11 and later and in C23, GHOSTTY_ENUM_TYPED expands to : int, which sets the enum's type to int directly.
C before C23 has no way to set an enum's type. Clang and GCC 13+ accept : int there as an extension, but -Wpedantic warns about it, so the macro expands to nothing in these modes. This keeps the headers free of warnings under -std=c11 -Wpedantic.
Without : int, the C compiler picks a type that can hold every value of the enum (C11 ยง6.7.2.2). To make sure that type is as large as int, every enum ends with a sentinel set to INT_MAX. The compiler still chooses the exact type, and whether it is signed.
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:
| #define GHOSTTY_INIT_SIZED | ( | 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 you compiled against.
| type | The struct type to initialize |
Example:
1.17.0