Respond to what programs ask of the terminal, such as the bell, title changes, and queries. More...

Detailed Description

Respond to what programs ask of the terminal, such as the bell, title changes, and queries.

An effect is a callback the terminal calls when a program asks for something the terminal can't do by itself, such as ringing the bell or changing the window title.

You need these as soon as a real program runs in the terminal. Until you register one, the terminal ignores that request, and a program that asks a question gets no answer. If you only feed bytes in to read the result back, you can skip this page.

Example

ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_BELL,

(const void*)on_bell);

ghostty_terminal_set

GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal, GhosttyTerminalOption option, const void *value)

GHOSTTY_TERMINAL_OPT_BELL

@ GHOSTTY_TERMINAL_OPT_BELL

Definition terminal.h:2058

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

See the Effects guide for how to register them, the rules for callbacks, the list of effects, and examples.

Enumerations
enum	GhosttyColorScheme

Data Structures
struct	GhosttyDeviceAttributesPrimary
struct	GhosttyDeviceAttributesSecondary
struct	GhosttyDeviceAttributesTertiary
struct	GhosttyDeviceAttributes
struct	GhosttyTerminalUnknownStringSequence
struct	GhosttyTerminalUnknownOscSequence
union	GhosttyTerminalUnknownSequenceValue
struct	GhosttyTerminalUnknownSequence
struct	GhosttyClipboardContent
struct	GhosttyClipboardWriteReply
struct	GhosttyClipboardWrite
struct	GhosttyClipboardReadReply
struct	GhosttyClipboardRead
struct	GhosttyTerminalDesktopNotification
struct	GhosttyTerminalProgressReport
struct	GhosttyTerminalProgramStatus
struct	GhosttyTerminalSemanticPrompt
struct	GhosttyTerminalResizeWindowGrid
union	GhosttyTerminalResizeWindowValue
struct	GhosttyTerminalResizeWindow

Unknown Sequences
enum	GhosttyTerminalUnknownSequenceTag { GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_APC = 0 , GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_OSC = 1 , GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyTerminalUnknownSequenceFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalUnknownSequence sequence)

Clipboard
enum	GhosttyClipboardLocation { GHOSTTY_CLIPBOARD_LOCATION_STANDARD = 0 , GHOSTTY_CLIPBOARD_LOCATION_SELECTION = 1 , GHOSTTY_CLIPBOARD_LOCATION_PRIMARY = 2 , GHOSTTY_CLIPBOARD_LOCATION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyClipboardWriteResult { GHOSTTY_CLIPBOARD_WRITE_RESULT_SUCCESS = 0 , GHOSTTY_CLIPBOARD_WRITE_RESULT_DENIED = 1 , GHOSTTY_CLIPBOARD_WRITE_RESULT_UNSUPPORTED = 2 , GHOSTTY_CLIPBOARD_WRITE_RESULT_BUSY = 3 , GHOSTTY_CLIPBOARD_WRITE_RESULT_INVALID_DATA = 4 , GHOSTTY_CLIPBOARD_WRITE_RESULT_IO_ERROR = 5 , GHOSTTY_CLIPBOARD_WRITE_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyClipboardReadResult { GHOSTTY_CLIPBOARD_READ_RESULT_SUCCESS = 0 , GHOSTTY_CLIPBOARD_READ_RESULT_DENIED = 1 , GHOSTTY_CLIPBOARD_READ_RESULT_UNSUPPORTED = 2 , GHOSTTY_CLIPBOARD_READ_RESULT_BUSY = 3 , GHOSTTY_CLIPBOARD_READ_RESULT_IO_ERROR = 4 , GHOSTTY_CLIPBOARD_READ_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyClipboardWriteReplyFn) (const GhosttyClipboardWrite write, const GhosttyClipboardWriteReply reply)
typedef void(*	GhosttyTerminalClipboardWriteFn) (GhosttyTerminal terminal, void userdata, const GhosttyClipboardWrite write)
typedef void(*	GhosttyClipboardReadReplyFn) (const GhosttyClipboardRead read, const GhosttyClipboardReadReply reply)
typedef void(*	GhosttyTerminalClipboardReadFn) (GhosttyTerminal terminal, void userdata, const GhosttyClipboardRead read)

Progress Reports
enum	GhosttyTerminalProgressState { GHOSTTY_TERMINAL_PROGRESS_STATE_REMOVE = 0 , GHOSTTY_TERMINAL_PROGRESS_STATE_SET = 1 , GHOSTTY_TERMINAL_PROGRESS_STATE_ERROR = 2 , GHOSTTY_TERMINAL_PROGRESS_STATE_INDETERMINATE = 3 , GHOSTTY_TERMINAL_PROGRESS_STATE_PAUSE = 4 , GHOSTTY_TERMINAL_PROGRESS_STATE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyTerminalProgressReportFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalProgressReport report)

Program Status
enum	GhosttyProgramStatusState { GHOSTTY_PROGRAM_STATUS_STATE_IDLE = 0 , GHOSTTY_PROGRAM_STATUS_STATE_WORKING = 1 , GHOSTTY_PROGRAM_STATUS_STATE_DONE = 2 , GHOSTTY_PROGRAM_STATUS_STATE_BLOCKED = 3 , GHOSTTY_PROGRAM_STATUS_STATE_ERROR = 4 , GHOSTTY_PROGRAM_STATUS_STATE_CLEAR = 5 , GHOSTTY_PROGRAM_STATUS_STATE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyProgramStatusKind { GHOSTTY_PROGRAM_STATUS_KIND_NONE = 0 , GHOSTTY_PROGRAM_STATUS_KIND_PERMISSION = 1 , GHOSTTY_PROGRAM_STATUS_KIND_QUESTION = 2 , GHOSTTY_PROGRAM_STATUS_KIND_AUTH = 3 , GHOSTTY_PROGRAM_STATUS_KIND_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyTerminalProgramStatusFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalProgramStatus report)

Semantic Prompts
enum	GhosttySemanticPromptKind { GHOSTTY_SEMANTIC_PROMPT_INVALID = 0 , GHOSTTY_SEMANTIC_PROMPT_PROMPT_START = 1 , GHOSTTY_SEMANTIC_PROMPT_INPUT_START = 2 , GHOSTTY_SEMANTIC_PROMPT_OUTPUT_START = 3 , GHOSTTY_SEMANTIC_PROMPT_COMMAND_END = 4 , GHOSTTY_SEMANTIC_PROMPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttySemanticPromptPromptKind { GHOSTTY_SEMANTIC_PROMPT_PROMPT_PRIMARY = 0 , GHOSTTY_SEMANTIC_PROMPT_PROMPT_RIGHT = 1 , GHOSTTY_SEMANTIC_PROMPT_PROMPT_CONTINUATION = 2 , GHOSTTY_SEMANTIC_PROMPT_PROMPT_SECONDARY = 3 , GHOSTTY_SEMANTIC_PROMPT_PROMPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyTerminalSemanticPromptFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalSemanticPrompt event)

Reset and Resize
enum	GhosttyTerminalResizeWindowTag { GHOSTTY_TERMINAL_RESIZE_WINDOW_GRID = 0 , GHOSTTY_TERMINAL_RESIZE_WINDOW_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
typedef void(*	GhosttyTerminalResetFn) (GhosttyTerminal terminal, void *userdata)
typedef void(*	GhosttyTerminalResizeWindowFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalResizeWindow request)

Bell
typedef void(*	GhosttyTerminalBellFn) (GhosttyTerminal terminal, void *userdata)

Desktop Notifications
typedef void(*	GhosttyTerminalDesktopNotificationFn) (GhosttyTerminal terminal, void userdata, const GhosttyTerminalDesktopNotification notification)

Queries
typedef bool(*	GhosttyTerminalColorSchemeFn) (GhosttyTerminal terminal, void userdata, GhosttyColorScheme out_scheme)
typedef bool(*	GhosttyTerminalDeviceAttributesFn) (GhosttyTerminal terminal, void userdata, GhosttyDeviceAttributes out_attrs)
typedef GhosttyString(*	GhosttyTerminalEnquiryFn) (GhosttyTerminal terminal, void *userdata)
typedef bool(*	GhosttyTerminalSizeFn) (GhosttyTerminal terminal, void userdata, GhosttySizeReportSize out_size)

Terminal State
typedef void(*	GhosttyTerminalTitleChangedFn) (GhosttyTerminal terminal, void *userdata)
typedef void(*	GhosttyTerminalRenderHoldFn) (GhosttyTerminal terminal, void *userdata, bool held)
typedef void(*	GhosttyTerminalPwdChangedFn) (GhosttyTerminal terminal, void *userdata)

Replies
typedef void(*	GhosttyTerminalWritePtyFn) (GhosttyTerminal terminal, void userdata, const uint8_t data, size_t len)
typedef GhosttyString(*	GhosttyTerminalXtversionFn) (GhosttyTerminal terminal, void *userdata)

Typedef Documentation

◆ GhosttyClipboardReadReplyFn

typedef void(* GhosttyClipboardReadReplyFn) (const GhosttyClipboardRead *read, const GhosttyClipboardReadReply *reply)

Function type used to answer a clipboard read request. Obtained from GhosttyClipboardRead::reply; see that struct for the contract.

Parameters

read	The request being answered
reply	The reply, borrowed only for the duration of this call

Definition at line 1026 of file terminal.h.

◆ GhosttyClipboardWriteReplyFn

typedef void(* GhosttyClipboardWriteReplyFn) (const GhosttyClipboardWrite *write, const GhosttyClipboardWriteReply *reply)

Function type used to answer a clipboard write request. Obtained from GhosttyClipboardWrite::reply; see that struct for the contract.

Parameters

write	The request being answered
reply	The reply, borrowed only for the duration of this call

Definition at line 844 of file terminal.h.

◆ GhosttyTerminalBellFn

typedef void(* GhosttyTerminalBellFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for bell.

Called when the terminal receives a BEL character (0x07).

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 575 of file terminal.h.

◆ GhosttyTerminalClipboardReadFn

typedef void(* GhosttyTerminalClipboardReadFn) (GhosttyTerminal terminal, void *userdata, const GhosttyClipboardRead *read)

Callback function type for clipboard_read.

Called synchronously when the running program requests clipboard contents via OSC 52 with a "?" payload or a Kitty clipboard (OSC 5522) read. Answering lets the program read the clipboard of the person using your terminal, so you are expected to mediate consent. Because the read is synchronous, an embedder that needs to ask them must block (for example by running a modal prompt) until it has an answer; the VT stream waits until the callback returns.

Answer by calling read->reply(read, &reply) before returning. See GhosttyClipboardRead for the full contract.

OSC 5522 requests carry the program's MIME list, name, and password grant state; a reply that sets remember records a session grant so later requests with the same password arrive with granted set. Kitty itself serves a request for only the targets listing (list with no mimes) without prompting, and embedders are expected to do the same; the terminal never consults grants for such requests (granted is false and one-time passwords are not consumed).

Installing this callback also enables Kitty paste events (mode 5522): ghostty_terminal_paste() sends the program an event instead of the text, and the program's follow-up read arrives here with granted set since the user already pasted. See ghostty_terminal_paste().

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
read	Borrowed clipboard read request

Definition at line 1133 of file terminal.h.

◆ GhosttyTerminalClipboardWriteFn

typedef void(* GhosttyTerminalClipboardWriteFn) (GhosttyTerminal terminal, void *userdata, const GhosttyClipboardWrite *write)

Callback function type for clipboard_write.

You may ask for permission to write or perform the write async, but the callback itself is synchronous and the reply function must be called during the lifetime of this function. While this callback is active the VT stream is paused.

Answer by calling write->reply(write, &reply) before returning. See GhosttyClipboardWrite for the full contract.

The request may carry an optional program name requesting the write and the state of prior permission granted. If can_remember is set the response may set the remember flag and future requests from this same program will be "granted" and you can skip permission requests.

Clipboard read requests (OSC 52 "?" and OSC 5522 reads) are delivered to GhosttyTerminalClipboardReadFn instead.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
write	Borrowed atomic clipboard write request

Definition at line 935 of file terminal.h.

◆ GhosttyTerminalColorSchemeFn

typedef bool(* GhosttyTerminalColorSchemeFn) (GhosttyTerminal terminal, void *userdata, GhosttyColorScheme *out_scheme)

Callback function type for color scheme queries (CSI ? 996 n).

Called when the terminal receives a color scheme device status report query. Return true and fill *out_scheme with the current color scheme, or return false to silently ignore the query.

The library sets *out_scheme to GHOSTTY_COLOR_SCHEME_LIGHT (zero) before the call, so returning true without writing it reports light. If the callback writes a value that isn't a GhosttyColorScheme, the library ignores the query, the same as if the callback returned false.

Parameters

	terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_scheme	Pointer to store the current color scheme

Returns: true if the color scheme was filled, false to ignore the query

Definition at line 1761 of file terminal.h.

◆ GhosttyTerminalDesktopNotificationFn

typedef void(* GhosttyTerminalDesktopNotificationFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalDesktopNotification *notification)

Callback function type for desktop notifications.

Called synchronously when the terminal receives OSC 9 or OSC 777.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
notification	Borrowed desktop notification request

Definition at line 1176 of file terminal.h.

◆ GhosttyTerminalDeviceAttributesFn

typedef bool(* GhosttyTerminalDeviceAttributesFn) (GhosttyTerminal terminal, void *userdata, GhosttyDeviceAttributes *out_attrs)

Callback function type for device attributes queries (DA1/DA2/DA3).

Called when the terminal receives a device attributes query (CSI c, CSI > c, or CSI = c). Return true and fill *out_attrs with the response data, or return false to silently ignore the query.

The terminal uses whichever sub-struct (primary, secondary, tertiary) matches the request type, but all three should be filled for simplicity.

The library zeroes *out_attrs before the call, so you only need to set the fields you want to report. Every field you leave alone is reported as zero. This callback reports a VT220 with color and clipboard support, and leaves the tertiary unit ID at zero:

static bool on_device_attributes(GhosttyTerminal terminal,
                                 void* userdata,
                                 GhosttyDeviceAttributes* out_attrs) {
  out_attrs->primary.conformance_level = GHOSTTY_DA_CONFORMANCE_VT220;
  out_attrs->primary.features[0] = GHOSTTY_DA_FEATURE_ANSI_COLOR;
  out_attrs->primary.features[1] = GHOSTTY_DA_FEATURE_CLIPBOARD;
  out_attrs->primary.num_features = 2;
  out_attrs->secondary.device_type = GHOSTTY_DA_DEVICE_TYPE_VT220;
  return true;
}

GhosttyDeviceAttributes is frozen. If a later version of libghostty-vt needs more fields, it adds a new callback typedef and a new option key, and keeps calling this callback with GhosttyDeviceAttributes forever. A callback written against this header keeps working with every later version of the library.

Parameters

	terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_attrs	Pointer to store the device attributes response

Returns: true if attributes were filled, false to ignore the query

Definition at line 1806 of file terminal.h.

◆ GhosttyTerminalEnquiryFn

typedef GhosttyString(* GhosttyTerminalEnquiryFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for enquiry (ENQ, 0x05).

Called when the terminal receives an ENQ character. Return the response bytes as a GhosttyString. The memory must remain valid until the callback returns. Return a zero-length string to send no response.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Returns: The response bytes to write back to the pty

Definition at line 1824 of file terminal.h.

◆ GhosttyTerminalProgramStatusFn

typedef void(* GhosttyTerminalProgramStatusFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalProgramStatus *report)

Callback function type for program status reports (OSC 7501).

Called synchronously each time the running program sends a valid report. See GhosttyTerminalProgramStatus for what a report contains.

The terminal doesn't store reports, so your application keeps them. To follow the specification, keep one record per id. A report with an empty id is about the root record, the program itself. The records follow these rules:

A report replaces its record completely. A value the report leaves out is gone from the record afterwards. It doesn't keep its old value.
A GHOSTTY_PROGRAM_STATUS_STATE_CLEAR report removes the record with its id and every record beneath it, so clearing "build" also removes "build/test". A clear report with an empty id removes every record.
A record without an app takes it from its nearest ancestor that has one. If the root record has app "deploy" and the record "us-east" has none, show "us-east" with app "deploy" too.
When a new shell prompt starts (GHOSTTY_SEMANTIC_PROMPT_PROMPT_START from the GHOSTTY_TERMINAL_OPT_SEMANTIC_PROMPT callback) or the program running in the terminal exits, remove working and blocked records. You may remove idle records too. Keep done and error records until the user has seen them, for example until they next focus the terminal.
Keep at most 256 records, and allow at least 64. When a new record would go over your limit, remove the one that was updated longest ago.

A full reset (RIS, ESC c) removes every record. When that happens, the terminal calls this with a GHOSTTY_PROGRAM_STATUS_STATE_CLEAR report and an empty id, and then calls the GHOSTTY_TERMINAL_OPT_RESET callback.

title and message are already decoded and contain no control characters, but they are still untrusted text from the program. Don't treat them as markup. If you show them outside the terminal, such as in a tab or a notification, remove invisible formatting characters like text direction overrides, and say which terminal the text came from so a program can't pretend to be one running elsewhere.

Example, where Records, records_clear, and records_put stand in for your application's own storage:

void on_program_status(GhosttyTerminal terminal,
                       void* userdata,
                       const GhosttyTerminalProgramStatus* report) {
  (void)terminal;
  Records* records = userdata;
 
  if (report->state == GHOSTTY_PROGRAM_STATUS_STATE_CLEAR) {
    // Remove this record and every record beneath it. An empty id
    // removes every record.
    records_clear(records, report->id);
    return;
  }
 
  // Replace the whole record. The strings are only valid during this
  // call, so records_put must copy them.
  records_put(records, report->id, report->state, report->message);
}
 
// Set write_pty too, so programs that check for support get a reply.
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_USERDATA, records);
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
                     (const void*)on_write_pty);
ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_PROGRAM_STATUS,
                     (const void*)on_program_status);

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
report	The report. It and its strings are only valid during the call.

Definition at line 1469 of file terminal.h.

◆ GhosttyTerminalProgressReportFn

typedef void(* GhosttyTerminalProgressReportFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalProgressReport *report)

Callback function type for progress reports.

Called synchronously when the terminal receives OSC 9;4.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
report	Borrowed progress report

Definition at line 1239 of file terminal.h.

◆ GhosttyTerminalPwdChangedFn

typedef void(* GhosttyTerminalPwdChangedFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for pwd_changed.

Called when the terminal pwd (current working directory) changes via escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.

The terminal stores whatever bytes the shell emitted, without parsing. That means for OSC 7 the value is the raw URI (typically file://...); for OSC 9/OSC 1337 it is typically a bare path. You are responsible for decoding any URI scheme or host if it cares about them.

The callback also fires when the shell clears the pwd (e.g. an empty OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length string.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 1946 of file terminal.h.

◆ GhosttyTerminalRenderHoldFn

typedef void(* GhosttyTerminalRenderHoldFn) (GhosttyTerminal terminal, void *userdata, bool held)

Callback function type for render_hold.

Called when the running program asks the terminal to stop updating the screen, and again when it lets the screen update again. We call the time in between a "render hold". See Render holds for what to do about one.

held is true when the program sets mode 2026 (GHOSTTY_MODE_SYNC_OUTPUT), which is the only way to start a hold today.

held is false when the hold ends, which happens when:

the program resets mode 2026
the terminal is fully reset, by the program (RIS) or by ghostty_terminal_reset()
the terminal is resized with ghostty_terminal_resize()

The two calls always come in pairs. Setting the mode while a hold is already active does nothing, and neither does resetting it when there is no hold. Changing the mode yourself with GHOSTTY_TERMINAL_OPT_MODE never invokes the callback.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
held	True when a hold begins, false when it ends

Definition at line 1920 of file terminal.h.

◆ GhosttyTerminalResetFn

typedef void(* GhosttyTerminalResetFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for reset.

Called when the running program performs a full reset (RIS, ESC c). A full reset clears the screen and scrollback, returns modes to their defaults, and clears the title and working directory. Use this callback to reset any state your application keeps about what's running in the terminal, such as the current command.

The terminal has already reset itself when this is called. The GHOSTTY_TERMINAL_OPT_TITLE_CHANGED and GHOSTTY_TERMINAL_OPT_PWD_CHANGED callbacks are not called for the cleared title and working directory, so update anything you show for them here. A full reset also removes any progress report and program status records. If you set GHOSTTY_TERMINAL_OPT_PROGRESS_REPORT or GHOSTTY_TERMINAL_OPT_PROGRAM_STATUS, those callbacks are called before this one.

A soft reset (DECSTR, CSI ! p) keeps the screen, title and working directory, and doesn't call this.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 1657 of file terminal.h.

◆ GhosttyTerminalResizeWindowFn

typedef void(* GhosttyTerminalResizeWindowFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalResizeWindow *request)

Callback function type for window resize requests.

Called synchronously when the running program asks to resize the window, such as with CSI 8 ; rows ; columns t. Check request->tag first, because more kinds of requests may be reported in later versions. The terminal is not resized by this: you decide whether to allow the request, and if so resizes its window and the terminal. Letting any program resize the window is a nuisance at best, so consider making this opt-in for users.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
request	Borrowed resize request

Definition at line 1731 of file terminal.h.

◆ GhosttyTerminalSemanticPromptFn

typedef void(* GhosttyTerminalSemanticPromptFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalSemanticPrompt *event)

Callback function type for semantic_prompt.

Called when the shell reports a step of a command. Each command goes through four steps, in this order: the prompt starts, input starts, output starts, and the command ends. Then the next prompt starts.

Shells differ in what they report. Many don't send the command line or the exit code, and some skip steps, so handle each event on its own instead of expecting a strict order. A shell may also start the same prompt more than once, for example when it redraws the prompt after a resize, so treat a repeated GHOSTTY_SEMANTIC_PROMPT_PROMPT_START as harmless.

The terminal has already updated its screen when this is called. A sequence the terminal rejects as malformed is never reported.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
event	The event. It and its strings are only valid during the call.

Definition at line 1620 of file terminal.h.

◆ GhosttyTerminalSizeFn

typedef bool(* GhosttyTerminalSizeFn) (GhosttyTerminal terminal, void *userdata, GhosttySizeReportSize *out_size)

Callback function type for terminal size reports.

Called in response to XTWINOPS size queries (CSI 14/16/18/19 t) and when VT input enables in-band size reports (mode 2048). Return true and fill *out_size with the current terminal geometry, or return false to suppress the report.

The library zeroes *out_size before the call, so any field you don't write reads as zero. A typical callback copies the geometry from your own window state, passed in through GHOSTTY_TERMINAL_OPT_USERDATA:

static bool on_size(GhosttyTerminal terminal,
                    void* userdata,
                    GhosttySizeReportSize* out_size) {
  const MyWindow* window = userdata;
  out_size->rows = window->rows;
  out_size->columns = window->columns;
  out_size->cell_width = window->cell_width;
  out_size->cell_height = window->cell_height;
  return true;
}

GhosttySizeReportSize is frozen. If a later version of libghostty-vt needs more fields, it adds a new callback typedef and a new option key, and keeps calling this callback with GhosttySizeReportSize forever. A callback written against this header keeps working with every later version of the library.

Parameters

	terminal	The terminal handle
	userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
[out]	out_size	Pointer to store the terminal size information

Returns: true if size was filled, false to suppress the XTWINOPS response or mode 2048 report

Definition at line 1866 of file terminal.h.

◆ GhosttyTerminalTitleChangedFn

typedef void(* GhosttyTerminalTitleChangedFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for title_changed.

Called when the terminal title changes via escape sequences (e.g. OSC 0 or OSC 2). Use ghostty_terminal_get() with GHOSTTY_TERMINAL_DATA_TITLE inside the callback to read the new value.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Definition at line 1888 of file terminal.h.

◆ GhosttyTerminalUnknownSequenceFn

typedef void(* GhosttyTerminalUnknownSequenceFn) (GhosttyTerminal terminal, void *userdata, const GhosttyTerminalUnknownSequence *sequence)

Callback function type for unsupported terminal sequences.

Called once for each complete sequence that libghostty-vt does not implement. Check sequence->tag first, because more kinds of sequences may be reported in later versions.

These are not reported:

Sequences cut short before their terminator, either cancelled by CAN or SUB or aborted by another 8-bit control byte.
Sequences libghostty-vt implements, even when their contents are malformed.
Supported protocols that you turned off.

The callback runs during ghostty_terminal_vt_write(). It may write a reply to the pty, and that reply stays in order with the terminal's own replies. It must not call ghostty_terminal_vt_write() on the same terminal.

Nothing is reported until GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES is also set to a nonzero value. Installing the callback by itself keeps no data and allocates no memory.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
sequence	Borrowed unsupported sequence

Definition at line 722 of file terminal.h.

◆ GhosttyTerminalWritePtyFn

typedef void(* GhosttyTerminalWritePtyFn) (GhosttyTerminal terminal, void *userdata, const uint8_t *data, size_t len)

Callback function type for write_pty.

Called when the terminal needs to write data back to the pty, for example in response to a device status report, mode query, or VT-driven mode 2048 enable. The data is only valid for the duration of the call; you must copy it if it needs to persist.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
data	Pointer to the response bytes
len	Length of the response in bytes

Definition at line 1970 of file terminal.h.

◆ GhosttyTerminalXtversionFn

typedef GhosttyString(* GhosttyTerminalXtversionFn) (GhosttyTerminal terminal, void *userdata)

Callback function type for XTVERSION.

Called when the terminal receives an XTVERSION query (CSI > q). Return the version string (e.g. "myterm 1.0") as a GhosttyString. The memory must remain valid until the callback returns. Return a zero-length string to report the default "libghostty" version.

Parameters

terminal	The terminal handle
userdata	The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA

Returns: The version string to report

Definition at line 1989 of file terminal.h.

Enumeration Type Documentation

◆ GhosttyClipboardLocation

enum GhosttyClipboardLocation

Clipboard destination for a clipboard write.

Protocol-specific destination identifiers are normalized to these values before the clipboard write callback is invoked.

Enumerator
GHOSTTY_CLIPBOARD_LOCATION_STANDARD	The standard system clipboard.
GHOSTTY_CLIPBOARD_LOCATION_SELECTION	The selection clipboard.
GHOSTTY_CLIPBOARD_LOCATION_PRIMARY	The primary selection clipboard.

Definition at line 741 of file terminal.h.

◆ GhosttyClipboardReadResult

enum GhosttyClipboardReadResult

Result of a clipboard read reply.

Enumerator
GHOSTTY_CLIPBOARD_READ_RESULT_SUCCESS	The clipboard was read; the reply carries its contents.
GHOSTTY_CLIPBOARD_READ_RESULT_DENIED	The clipboard read was denied by policy or the user.
GHOSTTY_CLIPBOARD_READ_RESULT_UNSUPPORTED	You cannot read this clipboard.
GHOSTTY_CLIPBOARD_READ_RESULT_BUSY	The clipboard is temporarily unavailable.
GHOSTTY_CLIPBOARD_READ_RESULT_IO_ERROR	Reading the clipboard failed due to an I/O error.

Definition at line 945 of file terminal.h.

◆ GhosttyClipboardWriteResult

enum GhosttyClipboardWriteResult

Result of a clipboard write reply.

Enumerator
GHOSTTY_CLIPBOARD_WRITE_RESULT_SUCCESS	The clipboard write completed successfully.
GHOSTTY_CLIPBOARD_WRITE_RESULT_DENIED	The clipboard write was denied by policy or the user.
GHOSTTY_CLIPBOARD_WRITE_RESULT_UNSUPPORTED	The destination or one or more representations are unsupported.
GHOSTTY_CLIPBOARD_WRITE_RESULT_BUSY	The clipboard is temporarily unavailable.
GHOSTTY_CLIPBOARD_WRITE_RESULT_INVALID_DATA	One or more representations contain invalid data.
GHOSTTY_CLIPBOARD_WRITE_RESULT_IO_ERROR	The clipboard write failed due to an I/O error.

Definition at line 778 of file terminal.h.

◆ GhosttyColorScheme

enum GhosttyColorScheme

Color scheme reported in response to a CSI ? 996 n query.

Definition at line 76 of file device.h.

◆ GhosttyProgramStatusKind

enum GhosttyProgramStatusKind

What a blocked program needs from the user, in a program status report (OSC 7501).

Enumerator
GHOSTTY_PROGRAM_STATUS_KIND_NONE	The program didn't say, or the state isn't GHOSTTY_PROGRAM_STATUS_STATE_BLOCKED.
GHOSTTY_PROGRAM_STATUS_KIND_PERMISSION	Approval to do something, such as "Apply these changes?".
GHOSTTY_PROGRAM_STATUS_KIND_QUESTION	An answer the user has to type.
GHOSTTY_PROGRAM_STATUS_KIND_AUTH	A login, password, token, or other credential.

Definition at line 1289 of file terminal.h.

◆ GhosttyProgramStatusState

enum GhosttyProgramStatusState

What a program says it is doing, in a program status report (OSC 7501).

See GhosttyTerminalProgramStatus for an overview of the protocol.

Enumerator
GHOSTTY_PROGRAM_STATUS_STATE_IDLE	At rest, waiting for the user's next instruction. For example, an interactive tool sitting at its own prompt.
GHOSTTY_PROGRAM_STATUS_STATE_WORKING	Running on its own. The report may include a progress percentage.
GHOSTTY_PROGRAM_STATUS_STATE_DONE	Finished a piece of work, and the result is ready for the user to look at.
GHOSTTY_PROGRAM_STATUS_STATE_BLOCKED	Can't continue until the user does something. kind says what the program needs and message says why. The report may include a progress percentage.
GHOSTTY_PROGRAM_STATUS_STATE_ERROR	Failed and stopped.
GHOSTTY_PROGRAM_STATUS_STATE_CLEAR	Not a real state. Remove the record with this report's id and every record beneath it. If the id is empty, remove every record.

Definition at line 1257 of file terminal.h.

◆ GhosttySemanticPromptKind

enum GhosttySemanticPromptKind

The step of a command that a shell integration event reports.

More kinds may be added in later versions, so ignore any kind you don't handle.

Enumerator
GHOSTTY_SEMANTIC_PROMPT_INVALID	Never reported. This exists so that a zeroed value is not mistaken for a real event.
GHOSTTY_SEMANTIC_PROMPT_PROMPT_START	The shell started drawing a prompt. prompt_kind says which one.
GHOSTTY_SEMANTIC_PROMPT_INPUT_START	The prompt is drawn and the user can start typing a command.
GHOSTTY_SEMANTIC_PROMPT_OUTPUT_START	The user submitted the command and it started running. Anything the terminal receives after this is the command's output.
GHOSTTY_SEMANTIC_PROMPT_COMMAND_END	The command finished running.

Definition at line 1488 of file terminal.h.

◆ GhosttySemanticPromptPromptKind

enum GhosttySemanticPromptPromptKind

Which prompt a GHOSTTY_SEMANTIC_PROMPT_PROMPT_START event starts.

Most shells only draw a primary prompt. Some also draw a prompt on the right side of the line, or a prompt at the start of each extra line when a command spans several lines.

Enumerator
GHOSTTY_SEMANTIC_PROMPT_PROMPT_PRIMARY	The main prompt shown before each command. This is used when the shell doesn't say which prompt it is drawing.
GHOSTTY_SEMANTIC_PROMPT_PROMPT_RIGHT	A prompt drawn at the right edge of the line, such as zsh's RPROMPT.
GHOSTTY_SEMANTIC_PROMPT_PROMPT_CONTINUATION	A prompt at the start of an extra line of a command that spans several lines.
GHOSTTY_SEMANTIC_PROMPT_PROMPT_SECONDARY	Another prompt for an extra line of input, such as bash's PS2. Shells differ in whether they report extra lines as continuation or secondary prompts, so most applications should treat the two the same.

Definition at line 1517 of file terminal.h.

◆ GhosttyTerminalProgressState

enum GhosttyTerminalProgressState

State of a terminal progress report.

Enumerator
GHOSTTY_TERMINAL_PROGRESS_STATE_REMOVE	Remove any visible progress indication.
GHOSTTY_TERMINAL_PROGRESS_STATE_SET	Show determinate progress.
GHOSTTY_TERMINAL_PROGRESS_STATE_ERROR	Show a failed progress state.
GHOSTTY_TERMINAL_PROGRESS_STATE_INDETERMINATE	Show indeterminate progress.
GHOSTTY_TERMINAL_PROGRESS_STATE_PAUSE	Show paused progress.

Definition at line 1192 of file terminal.h.

◆ GhosttyTerminalResizeWindowTag

enum GhosttyTerminalResizeWindowTag

The kind of window resize request passed to a GhosttyTerminalResizeWindowFn callback.

New kinds may be added in later versions. Callbacks should ignore any tag they don't handle.

Enumerator
GHOSTTY_TERMINAL_RESIZE_WINDOW_GRID	Resize the window's text area to a size in rows and columns (CSI 8 ; rows ; columns t). The value is in value.grid.

Definition at line 1669 of file terminal.h.

◆ GhosttyTerminalUnknownSequenceTag

enum GhosttyTerminalUnknownSequenceTag

The kind of unsupported sequence passed to a GhosttyTerminalUnknownSequenceFn callback.

New kinds may be added in later versions. Callbacks should ignore any tag they don't handle.

Enumerator
GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_APC	Application Program Command (APC).
GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_OSC	Operating System Command (OSC). The value is in value.osc.

Definition at line 593 of file terminal.h.

Detailed Description

Example

Enumerations

Data Structures

Unknown Sequences

Clipboard

Progress Reports

Program Status

Semantic Prompts

Reset and Resize

Bell

Desktop Notifications

Queries

Terminal State

Replies

Typedef Documentation

◆ GhosttyClipboardReadReplyFn

◆ GhosttyClipboardWriteReplyFn

◆ GhosttyTerminalBellFn

◆ GhosttyTerminalClipboardReadFn

◆ GhosttyTerminalClipboardWriteFn

◆ GhosttyTerminalColorSchemeFn

◆ GhosttyTerminalDesktopNotificationFn

◆ GhosttyTerminalDeviceAttributesFn

◆ GhosttyTerminalEnquiryFn

◆ GhosttyTerminalProgramStatusFn

◆ GhosttyTerminalProgressReportFn

◆ GhosttyTerminalPwdChangedFn

◆ GhosttyTerminalRenderHoldFn

◆ GhosttyTerminalResetFn

◆ GhosttyTerminalResizeWindowFn

◆ GhosttyTerminalSemanticPromptFn

◆ GhosttyTerminalSizeFn

◆ GhosttyTerminalTitleChangedFn

◆ GhosttyTerminalUnknownSequenceFn

◆ GhosttyTerminalWritePtyFn

◆ GhosttyTerminalXtversionFn

Enumeration Type Documentation

◆ GhosttyClipboardLocation

◆ GhosttyClipboardReadResult

◆ GhosttyClipboardWriteResult

◆ GhosttyColorScheme

◆ GhosttyProgramStatusKind

◆ GhosttyProgramStatusState

◆ GhosttySemanticPromptKind

◆ GhosttySemanticPromptPromptKind

◆ GhosttyTerminalProgressState

◆ GhosttyTerminalResizeWindowTag

◆ GhosttyTerminalUnknownSequenceTag