Core Types

Core types and data structures in the libghostty C API

Core Types

This page documents the core types and data structures used throughout the libghostty C API.

Opaque Types

These types are opaque pointers managed entirely by libghostty. Never dereference these pointers directly.

ghostty_app_t · void*

The main application instance. Manages global state, configuration, and coordinates multiple surfaces.

Created with ghostty_app_new() and freed with ghostty_app_free().

ghostty_config_t · void*

Configuration object containing terminal settings and behavior.

Created with ghostty_config_new() and freed with ghostty_config_free().

ghostty_surface_t · void*

A terminal surface (a single terminal instance). Each surface represents one terminal that can be rendered.

Created with ghostty_surface_new() and freed with ghostty_surface_free().

ghostty_inspector_t · void*

An inspector/debugger interface for viewing terminal state.

Obtained with ghostty_surface_inspector() and freed with ghostty_inspector_free().

Platform Types

ghostty_platform_e

Defines the target platform for a surface.

typedef enum {
  GHOSTTY_PLATFORM_INVALID,
  GHOSTTY_PLATFORM_MACOS,
  GHOSTTY_PLATFORM_IOS,
} ghostty_platform_e;

GHOSTTY_PLATFORM_INVALID · enum

Invalid/uninitialized platform.

GHOSTTY_PLATFORM_MACOS · enum

macOS platform with Metal rendering and NSView integration.

GHOSTTY_PLATFORM_IOS · enum

iOS platform with Metal rendering and UIView integration.

ghostty_platform_macos_s

Platform-specific data for macOS.

typedef struct {
  void* nsview;
} ghostty_platform_macos_s;

nsview · void*

Pointer to an NSView (cast to void*). The terminal will render into this view using Metal.

ghostty_platform_ios_s

Platform-specific data for iOS.

typedef struct {
  void* uiview;
} ghostty_platform_ios_s;

uiview · void*

Pointer to a UIView (cast to void*). The terminal will render into this view using Metal.

ghostty_platform_u

Union of platform-specific data.

typedef union {
  ghostty_platform_macos_s macos;
  ghostty_platform_ios_s ios;
} ghostty_platform_u;

Use the appropriate field based on ghostty_platform_e.

Surface Configuration

ghostty_surface_config_s

Configuration for creating a new terminal surface.

typedef struct {
  ghostty_platform_e platform_tag;
  ghostty_platform_u platform;
  void* userdata;
  double scale_factor;
  float font_size;
  const char* working_directory;
  const char* command;
  ghostty_env_var_s* env_vars;
  size_t env_var_count;
  const char* initial_input;
  bool wait_after_command;
  ghostty_surface_context_e context;
} ghostty_surface_config_s;

platform_tag · ghostty_platform_e · required

The target platform for this surface.

platform · ghostty_platform_u · required

Platform-specific configuration data. Use the field corresponding to platform_tag.

userdata · void*

Arbitrary pointer to user data. Retrieved with ghostty_surface_userdata().

scale_factor · double

Display scale factor (e.g., 2.0 for Retina displays). Used for high-DPI rendering.

font_size · float

Font size in points.

working_directory · const char*

Initial working directory for the shell. NULL for user’s home directory.

command · const char*

Command to run instead of the default shell. NULL for default shell.

env_vars · ghostty_env_var_s*

Array of environment variables to set for the shell.

env_var_count · size_t

Number of environment variables in env_vars.

initial_input · const char*

Text to send to the terminal after initialization. NULL for no initial input.

wait_after_command · bool

If true, keep the terminal open after the command exits.

context · ghostty_surface_context_e

Context in which the surface is being created (window, tab, split).

ghostty_surface_context_e

Defines the UI context for a surface.

typedef enum {
  GHOSTTY_SURFACE_CONTEXT_WINDOW = 0,
  GHOSTTY_SURFACE_CONTEXT_TAB = 1,
  GHOSTTY_SURFACE_CONTEXT_SPLIT = 2,
} ghostty_surface_context_e;

GHOSTTY_SURFACE_CONTEXT_WINDOW · enum

Surface is the primary terminal in a window.

GHOSTTY_SURFACE_CONTEXT_TAB · enum

Surface is in a tab.

GHOSTTY_SURFACE_CONTEXT_SPLIT · enum

Surface is in a split pane.

ghostty_surface_size_s

Describes the size of a terminal surface.

typedef struct {
  uint16_t columns;
  uint16_t rows;
  uint32_t width_px;
  uint32_t height_px;
  uint32_t cell_width_px;
  uint32_t cell_height_px;
} ghostty_surface_size_s;

columns · uint16_t

Number of character columns.

rows · uint16_t

Number of character rows.

width_px · uint32_t

Width in pixels.

height_px · uint32_t

Height in pixels.

cell_width_px · uint32_t

Width of a single character cell in pixels.

cell_height_px · uint32_t

Height of a single character cell in pixels.

Runtime Configuration

ghostty_runtime_config_s

Configuration for runtime callbacks that libghostty uses to communicate with the host application.

typedef struct {
  void* userdata;
  bool supports_selection_clipboard;
  ghostty_runtime_wakeup_cb wakeup_cb;
  ghostty_runtime_action_cb action_cb;
  ghostty_runtime_read_clipboard_cb read_clipboard_cb;
  ghostty_runtime_confirm_read_clipboard_cb confirm_read_clipboard_cb;
  ghostty_runtime_write_clipboard_cb write_clipboard_cb;
  ghostty_runtime_close_surface_cb close_surface_cb;
} ghostty_runtime_config_s;

userdata · void*

Arbitrary pointer passed to all callbacks. Retrieved with ghostty_app_userdata().

supports_selection_clipboard · bool

Whether the platform supports X11-style selection clipboard (middle-click paste).

wakeup_cb · ghostty_runtime_wakeup_cb · required

Callback invoked when libghostty needs the event loop to wake up.

typedef void (*ghostty_runtime_wakeup_cb)(void* userdata);

action_cb · ghostty_runtime_action_cb · required

Callback invoked when the terminal performs an action (ring bell, change title, etc.).

typedef bool (*ghostty_runtime_action_cb)(
    ghostty_app_t app,
    ghostty_target_s target,
    ghostty_action_s action
);

Return true if the action was handled, false otherwise.

read_clipboard_cb · ghostty_runtime_read_clipboard_cb

Callback invoked when the terminal needs to read from the clipboard.

typedef void (*ghostty_runtime_read_clipboard_cb)(
    void* userdata,
    ghostty_clipboard_e clipboard,
    void* request_userdata
);

confirm_read_clipboard_cb · ghostty_runtime_confirm_read_clipboard_cb

Callback invoked when the terminal needs confirmation before reading the clipboard (OSC 52).

typedef void (*ghostty_runtime_confirm_read_clipboard_cb)(
    void* userdata,
    const char* message,
    void* request_userdata,
    ghostty_clipboard_request_e request
);

write_clipboard_cb · ghostty_runtime_write_clipboard_cb

Callback invoked when the terminal needs to write to the clipboard.

typedef void (*ghostty_runtime_write_clipboard_cb)(
    void* userdata,
    ghostty_clipboard_e clipboard,
    const ghostty_clipboard_content_s* content,
    size_t content_count,
    bool confirm
);

close_surface_cb · ghostty_runtime_close_surface_cb

Callback invoked when a surface should be closed.

typedef void (*ghostty_runtime_close_surface_cb)(
    void* userdata,
    bool confirmed
);

Clipboard Types

ghostty_clipboard_e

Clipboard selection type.

typedef enum {
  GHOSTTY_CLIPBOARD_STANDARD,
  GHOSTTY_CLIPBOARD_SELECTION,
} ghostty_clipboard_e;

GHOSTTY_CLIPBOARD_STANDARD · enum

Standard system clipboard (Ctrl+C/Ctrl+V).

GHOSTTY_CLIPBOARD_SELECTION · enum

X11 selection clipboard (middle-click paste).

ghostty_clipboard_content_s

Content for clipboard operations.

typedef struct {
  const char* mime;
  const char* data;
} ghostty_clipboard_content_s;

mime · const char*

MIME type of the content (e.g., “text/plain”, “text/html”).

data · const char*

The clipboard data as a null-terminated string.

ghostty_clipboard_request_e

Type of clipboard request.

typedef enum {
  GHOSTTY_CLIPBOARD_REQUEST_PASTE,
  GHOSTTY_CLIPBOARD_REQUEST_OSC_52_READ,
  GHOSTTY_CLIPBOARD_REQUEST_OSC_52_WRITE,
} ghostty_clipboard_request_e;

Utility Types

ghostty_string_s

A string returned by libghostty that must be freed.

typedef struct {
  const char* ptr;
  uintptr_t len;
  bool sentinel;
} ghostty_string_s;

ptr · const char*

Pointer to the string data.

len · uintptr_t

Length of the string in bytes.

sentinel · bool

If true, the string is null-terminated.

Free with ghostty_string_free().

ghostty_info_s

Information about the libghostty build.

typedef struct {
  ghostty_build_mode_e build_mode;
  const char* version;
  uintptr_t version_len;
} ghostty_info_s;

build_mode · ghostty_build_mode_e

The build mode (debug, release, etc.).

version · const char*

Version string (not null-terminated, use version_len).

version_len · uintptr_t

Length of the version string.

ghostty_build_mode_e

typedef enum {
  GHOSTTY_BUILD_MODE_DEBUG,
  GHOSTTY_BUILD_MODE_RELEASE_SAFE,
  GHOSTTY_BUILD_MODE_RELEASE_FAST,
  GHOSTTY_BUILD_MODE_RELEASE_SMALL,
} ghostty_build_mode_e;

ghostty_diagnostic_s

A configuration diagnostic (warning or error).

typedef struct {
  const char* message;
} ghostty_diagnostic_s;

message · const char*

Human-readable diagnostic message.

Color Types

ghostty_color_scheme_e

System color scheme preference.

typedef enum {
  GHOSTTY_COLOR_SCHEME_LIGHT = 0,
  GHOSTTY_COLOR_SCHEME_DARK = 1,
} ghostty_color_scheme_e;

ghostty_config_color_s

RGB color value.

typedef struct {
  uint8_t r;
  uint8_t g;
  uint8_t b;
} ghostty_config_color_s;

r · uint8_t

Red component (0-255).

g · uint8_t

Green component (0-255).

b · uint8_t

Blue component (0-255).

Environment Variables

ghostty_env_var_s

An environment variable key-value pair.

typedef struct {
  const char* key;
  const char* value;
} ghostty_env_var_s;

key · const char*

Environment variable name.

value · const char*

Environment variable value.

Constants

GHOSTTY_SUCCESS

#define GHOSTTY_SUCCESS 0

Return value indicating successful operation. Used by functions like ghostty_init().

See Also

• Configuration API - Configuration types and functions
• Input Types - Input-related types
• Actions - Action types and rendering