### Start and Stop Terminal Driver

Source: https://context7.com/o11c/libtermkey/llms.txt

Use termkey_start and termkey_stop to temporarily release terminal settings for child process execution. Ensure termkey_start is called after the child process returns to reconfigure the terminal.

```c
#include <termkey.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/wait.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);

    printf("Reading keys... press 's' to spawn shell, 'q' to quit\n");

    TermKeyKey key;
    while (termkey_waitkey(tk, &key) == TERMKEY_RES_KEY) {
        if (key.type == TERMKEY_TYPE_UNICODE) {
            if (key.code.codepoint == 'q')
                break;

            if (key.code.codepoint == 's') {
                // Stop termkey to release terminal settings
                termkey_stop(tk);

                printf("Spawning shell... type 'exit' to return\n");
                pid_t pid = fork();
                if (pid == 0) {
                    execlp("sh", "sh", NULL);
                    exit(1);
                }
                waitpid(pid, NULL, 0);

                // Restart termkey to reconfigure terminal
                termkey_start(tk);
                printf("Back to key reading mode\n");
            }
        }

        char buf[50];
        termkey_strfkey(tk, buf, sizeof buf, &key, TERMKEY_FORMAT_VIM);
        printf("Key: %s\n", buf);
    }

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### Supply bytes directly with termkey_push_bytes

Source: https://context7.com/o11c/libtermkey/llms.txt

Pushes bytes directly into the termkey buffer for parsing. This is useful when bytes originate from sources other than a file descriptor. The example simulates receiving various escape sequences and regular text.

```c
#include <termkey.h>
#include <stdio.h>
#include <string.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key;
    char buffer[50];

    // Simulate receiving escape sequences
    const char *sequences[] = {
        "\x1b[A",       // Up arrow
        "\x1b[B",       // Down arrow
        "\x1b[1;5C",    // Ctrl-Right
        "hello",        // Regular text
        "\x1b[M !\"",   // Mouse click at (1,2)
    };

    for (int i = 0; i < 5; i++) {
        size_t len = strlen(sequences[i]);
        termkey_push_bytes(tk, sequences[i], len);

        while (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
            termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
            printf("Parsed: %s\n", buffer);
        }
    }
    // Output:
    // Parsed: <Up>
    // Parsed: <Down>
    // Parsed: <C-Right>
    // Parsed: h
    // Parsed: e
    // Parsed: l
    // Parsed: l
    // Parsed: o
    // Parsed: <M1>

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### Non-blocking key retrieval with termkey_getkey

Source: https://context7.com/o11c/libtermkey/llms.txt

Retrieves key events from the internal buffer without blocking. Returns TERMKEY_RES_NONE if no complete key is available, or TERMKEY_RES_AGAIN if a partial sequence was detected. This example also shows how to handle timeouts and exit on Ctrl-C.

```c
#include <termkey.h>
#include <poll.h>
#include <stdio.h>

static void on_key(TermKey *tk, TermKeyKey *key)
{
    char buffer[50];
    termkey_strfkey(tk, buffer, sizeof buffer, key, TERMKEY_FORMAT_VIM);
    printf("%s\n", buffer);
}

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    struct pollfd fd;
    fd.fd = 0;
    fd.events = POLLIN;

    TermKeyResult ret;
    TermKeyKey key;
    int running = 1;
    int nextwait = -1;

    while (running) {
        if (poll(&fd, 1, nextwait) == 0) {
            // Timeout - force interpretation of partial sequence
            if (termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
                on_key(tk, &key);
        }

        if (fd.revents & (POLLIN | POLLHUP | POLLERR))
            termkey_advisereadable(tk);

        // Process all available keys
        while ((ret = termkey_getkey(tk, &key)) == TERMKEY_RES_KEY) {
            on_key(tk, &key);

            // Exit on Ctrl-C
            if (key.type == TERMKEY_TYPE_UNICODE &&
                key.modifiers & TERMKEY_KEYMOD_CTRL &&
                (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
                running = 0;
        }

        if (ret == TERMKEY_RES_AGAIN)
            nextwait = termkey_get_waittime(tk);
        else
            nextwait = -1;
    }

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### Notify of available input with termkey_advisereadable

Source: https://context7.com/o11c/libtermkey/llms.txt

Informs the termkey instance that more bytes may be available on the file descriptor. This should be called when poll/select indicates the fd is readable. The example shows how to process keys after being notified.

```c
#include <termkey.h>
#include <poll.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    struct pollfd pfd = { .fd = 0, .events = POLLIN };

    while (1) {
        poll(&pfd, 1, -1);

        if (pfd.revents & POLLIN) {
            // Tell termkey to read available bytes
            TermKeyResult res = termkey_advisereadable(tk);

            if (res == TERMKEY_RES_AGAIN) {
                // Bytes were read, process keys
                TermKeyKey key;
                while (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
                    char buf[50];
                    termkey_strfkey(tk, buf, sizeof buf, &key, TERMKEY_FORMAT_VIM);
                    printf("Key: %s\n", buf);
                }
            }
        }
    }

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### termkey_set_flags / termkey_get_flags - Control flags

Source: https://context7.com/o11c/libtermkey/llms.txt

Gets or sets the operational flags controlling input interpretation, UTF-8 handling, and signal behavior.

```APIDOC
## termkey_set_flags / termkey_get_flags - Control flags

### Description
Gets or sets the operational flags controlling input interpretation, UTF-8 handling, and signal behavior.

### Method
(Not applicable, these are function calls within a C program)

### Endpoint
(Not applicable)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);

    // Get current flags
    int flags = termkey_get_flags(tk);
    printf("Initial flags: 0x%x\n", flags);

    if (flags & TERMKEY_FLAG_UTF8)
        printf("  UTF-8 mode enabled\n");
    if (flags & TERMKEY_FLAG_RAW)
        printf("  RAW mode enabled\n");

    // Enable additional flags
    termkey_set_flags(tk, flags | TERMKEY_FLAG_CONVERTKP | TERMKEY_FLAG_CTRLC);

    flags = termkey_get_flags(tk);
    printf("Updated flags: 0x%x\n", flags);

    if (flags & TERMKEY_FLAG_CONVERTKP)
        printf("  Keypad conversion enabled\n");
    if (flags & TERMKEY_FLAG_CTRLC)
        printf("  Ctrl-C readable (SIGINT disabled)\n");

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
(Not applicable, these are functions that return values or modify variables)

#### Response Example
(See Request Example for output format)
```

--------------------------------

### Control Termkey Operational Flags

Source: https://context7.com/o11c/libtermkey/llms.txt

Gets or sets the operational flags that control input interpretation, UTF-8 handling, and signal behavior. Use bitwise operations to modify flags. Initial flags can be retrieved using termkey_get_flags.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);

    // Get current flags
    int flags = termkey_get_flags(tk);
    printf("Initial flags: 0x%x\n", flags);

    if (flags & TERMKEY_FLAG_UTF8)
        printf("  UTF-8 mode enabled\n");
    if (flags & TERMKEY_FLAG_RAW)
        printf("  RAW mode enabled\n");

    // Enable additional flags
    termkey_set_flags(tk, flags | TERMKEY_FLAG_CONVERTKP | TERMKEY_FLAG_CTRLC);

    flags = termkey_get_flags(tk);
    printf("Updated flags: 0x%x\n", flags);

    if (flags & TERMKEY_FLAG_CONVERTKP)
        printf("  Keypad conversion enabled\n");
    if (flags & TERMKEY_FLAG_CTRLC)
        printf("  Ctrl-C readable (SIGINT disabled)\n");

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### Interpret Mouse Event Details

Source: https://context7.com/o11c/libtermkey/llms.txt

Interprets a mouse event key structure to extract button, position, and event type (press, drag, release). Ensure mouse tracking is enabled in the terminal before using this function. The example includes enabling and disabling mouse tracking.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, TERMKEY_FLAG_CTRLC);
    if (!tk) return 1;

    // Enable mouse tracking (mode 1000)
    printf("\033[?1000h");
    fflush(stdout);

    TermKeyKey key;
    char buffer[50];

    printf("Click mouse buttons (Ctrl-C to exit):\n");

    while (termkey_waitkey(tk, &key) == TERMKEY_RES_KEY) {
        if (key.type == TERMKEY_TYPE_MOUSE) {
            TermKeyMouseEvent ev;
            int button, line, col;

            termkey_interpret_mouse(tk, &key, &ev, &button, &line, &col);

            const char *evname;
            switch (ev) {
                case TERMKEY_MOUSE_PRESS:   evname = "press";   break;
                case TERMKEY_MOUSE_DRAG:    evname = "drag";    break;
                case TERMKEY_MOUSE_RELEASE: evname = "release"; break;
                default:                    evname = "unknown"; break;
            }

            termkey_strfkey(tk, buffer, sizeof buffer, &key,
                           TERMKEY_FORMAT_VIM | TERMKEY_FORMAT_MOUSE_POS);
            printf("Mouse %s: button=%d at line=%d, col=%d [%s]\n",
                   evname, button, line, col, buffer);
        }
        else if (key.type == TERMKEY_TYPE_UNICODE &&
                 key.modifiers & TERMKEY_KEYMOD_CTRL &&
                 key.code.codepoint == 'c') {
            break;
        }
    }

    // Disable mouse tracking
    printf("\033[?1000l");

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### Create Termkey Instance with File Descriptor

Source: https://context7.com/o11c/libtermkey/llms.txt

Creates a new termkey instance connected to a file descriptor (e.g., stdin). Configurable with flags for UTF-8, Ctrl-C handling, and more. Always check for allocation errors.

```c
#include <termkey.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    // Create instance reading from stdin (fd 0) with UTF-8 and Ctrl-C handling
    TermKey *tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL | TERMKEY_FLAG_CTRLC);

    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        exit(1);
    }

    // Check the encoding mode that was detected
    if (termkey_get_flags(tk) & TERMKEY_FLAG_UTF8)
        printf("Termkey in UTF-8 mode\n");
    else if (termkey_get_flags(tk) & TERMKEY_FLAG_RAW)
        printf("Termkey in RAW mode\n");

    // Use the instance...

    // Clean up when done
    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### Create Abstract Termkey Instance for Byte Parsing

Source: https://context7.com/o11c/libtermkey/llms.txt

Creates a termkey instance not connected to a file descriptor, suitable for parsing terminal bytes from sources like network connections. Bytes are pushed manually using `termkey_push_bytes`.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    // Create abstract instance for xterm-256color terminal type
    TermKey *tk = termkey_new_abstract("xterm-256color", 0);

    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    // Push bytes manually instead of reading from file descriptor
    const char input[] = "\x1b[A";  // Up arrow escape sequence
    termkey_push_bytes(tk, input, sizeof(input) - 1);

    TermKeyKey key;
    if (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
        char buffer[50];
        termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
        printf("Parsed key: %s\n", buffer);  // Output: <Up>
    }

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### Format Key Event to String

Source: https://context7.com/o11c/libtermkey/llms.txt

Converts a key event structure into a human-readable string. Use different format flags to control the output style, such as vim-style or urwid-style. Ensure the buffer is large enough to hold the formatted string.

```c
#include <termkey.h>
#include <stdio.h>
#include <string.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key;
    char buffer[50];

    // Create a Ctrl-Shift-A key event
    key.type = TERMKEY_TYPE_UNICODE;
    key.code.codepoint = 'A';
    key.modifiers = TERMKEY_KEYMOD_CTRL | TERMKEY_KEYMOD_SHIFT;
    key.utf8[0] = '\0';  // Let strfkey fill this

    // Different format styles
    termkey_strfkey(tk, buffer, sizeof buffer, &key, 0);
    printf("Default:    %s\n", buffer);    // C-S-A

    termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
    printf("Vim style:  %s\n", buffer);    // <C-S-A>

    termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_LONGMOD);
    printf("Long mods:  %s\n", buffer);    // Ctrl-Shift-A

    termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_URWID);
    printf("Urwid:      %s\n", buffer);    // ctrl shift a

    termkey_strfkey(tk, buffer, sizeof buffer, &key,
                    TERMKEY_FORMAT_ALTISMETA | TERMKEY_FORMAT_WRAPBRACKET);
    printf("Meta style: %s\n", buffer);    // <C-S-A>

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### termkey_new - Create a new termkey instance

Source: https://context7.com/o11c/libtermkey/llms.txt

Creates a new termkey instance connected to a file descriptor. This function handles terminal input parsing and can be configured with flags for UTF-8 handling, keypad conversion, and signal handling.

```APIDOC
## termkey_new - Create a new termkey instance

### Description
Creates a new termkey instance connected to a file descriptor. The instance handles all terminal input parsing and can be configured with various flags to control behavior like UTF-8 handling, keypad conversion, and signal handling.

### Method
`termkey_new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include <termkey.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    // Create instance reading from stdin (fd 0) with UTF-8 and Ctrl-C handling
    TermKey *tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL | TERMKEY_FLAG_CTRLC);

    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        exit(1);
    }

    // Check the encoding mode that was detected
    if (termkey_get_flags(tk) & TERMKEY_FLAG_UTF8)
        printf("Termkey in UTF-8 mode\n");
    else if (termkey_get_flags(tk) & TERMKEY_FLAG_RAW)
        printf("Termkey in RAW mode\n");

    // Use the instance...

    // Clean up when done
    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
Returns a pointer to a `TermKey` instance on success.

#### Response Example
(See C code example for usage)
```

--------------------------------

### termkey_keycmp - Compare key events

Source: https://context7.com/o11c/libtermkey/llms.txt

Compares two key events for ordering, useful for implementing keybinding lookup tables or sorting.

```APIDOC
## termkey_keycmp - Compare key events

### Description
Compares two key events for ordering, useful for implementing keybinding lookup tables or sorting.

### Method
(Not applicable, this is a function call within a C program)

### Endpoint
(Not applicable)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key1, key2;

    // Parse two keys for comparison
    termkey_strpkey(tk, "C-a", &key1, TERMKEY_FORMAT_VIM);
    termkey_strpkey(tk, "C-b", &key2, TERMKEY_FORMAT_VIM);

    int result = termkey_keycmp(tk, &key1, &key2);

    if (result < 0)
        printf("C-a comes before C-b\n");
    else if (result > 0)
        printf("C-a comes after C-b\n");
    else
        printf("Keys are identical\n");

    // Compare same keys
    termkey_strpkey(tk, "C-x", &key1, TERMKEY_FORMAT_VIM);
    termkey_strpkey(tk, "C-x", &key2, TERMKEY_FORMAT_VIM);

    if (termkey_keycmp(tk, &key1, &key2) == 0)
        printf("C-x equals C-x\n");

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
(Not applicable, this is a function that returns an integer)

#### Response Example
(See Request Example for output format)
```

--------------------------------

### Compare Key Events

Source: https://context7.com/o11c/libtermkey/llms.txt

Compares two key events for ordering, useful for implementing keybinding lookup tables or sorting. The function returns a negative value if key1 comes before key2, a positive value if key1 comes after key2, and zero if they are identical.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key1, key2;

    // Parse two keys for comparison
    termkey_strpkey(tk, "C-a", &key1, TERMKEY_FORMAT_VIM);
    termkey_strpkey(tk, "C-b", &key2, TERMKEY_FORMAT_VIM);

    int result = termkey_keycmp(tk, &key1, &key2);

    if (result < 0)
        printf("C-a comes before C-b\n");
    else if (result > 0)
        printf("C-a comes after C-b\n");
    else
        printf("Keys are identical\n");

    // Compare same keys
    termkey_strpkey(tk, "C-x", &key1, TERMKEY_FORMAT_VIM);
    termkey_strpkey(tk, "C-x", &key2, TERMKEY_FORMAT_VIM);

    if (termkey_keycmp(tk, &key1, &key2) == 0)
        printf("C-x equals C-x\n");

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### GLib Event Loop Integration for Termkey

Source: https://context7.com/o11c/libtermkey/llms.txt

Integrates termkey with the GLib main event loop for GUI or complex event-driven programs. Uses g_io_add_watch for stdin and g_timeout_add for handling key presses asynchronously.

```c
#include <stdio.h>
#include <glib.h>
#include <termkey.h>

static TermKey *tk;
static int timeout_id;

static void on_key(TermKey *tk, TermKeyKey *key)
{
    char buffer[50];
    termkey_strfkey(tk, buffer, sizeof buffer, key, TERMKEY_FORMAT_VIM);
    printf("%s\n", buffer);
}

static gboolean key_timer(gpointer data)
{
    TermKeyKey key;
    if (termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
        on_key(tk, &key);
    return FALSE;
}

static gboolean stdin_io(GIOChannel *source, GIOCondition condition, gpointer data)
{
    if (condition && G_IO_IN) {
        if (timeout_id)
            g_source_remove(timeout_id);

        termkey_advisereadable(tk);

        TermKeyResult ret;
        TermKeyKey key;
        while ((ret = termkey_getkey(tk, &key)) == TERMKEY_RES_KEY) {
            on_key(tk, &key);
        }

        if (ret == TERMKEY_RES_AGAIN)
            timeout_id = g_timeout_add(termkey_get_waittime(tk), key_timer, NULL);
    }
    return TRUE;
}

int main(int argc, char *argv[])
{
    TERMKEY_CHECK_VERSION;

    tk = termkey_new(0, 0);
    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    GMainLoop *loop = g_main_loop_new(NULL, FALSE);
    g_io_add_watch(g_io_channel_unix_new(0), G_IO_IN, stdin_io, NULL);
    g_main_loop_run(loop);

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### Configure Input Timeout

Source: https://context7.com/o11c/libtermkey/llms.txt

Controls the timeout in milliseconds for multi-byte sequence completion. When a partial escape sequence is detected, termkey waits this duration for more bytes before interpreting what's available. This is useful for adjusting responsiveness on different network conditions.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);

    // Get default wait time (usually 50ms)
    int waittime = termkey_get_waittime(tk);
    printf("Default wait time: %d ms\n", waittime);

    // Increase for high-latency connections (e.g., SSH)
    termkey_set_waittime(tk, 100);
    printf("New wait time: %d ms\n", termkey_get_waittime(tk));

    // Decrease for local, responsive terminals
    termkey_set_waittime(tk, 20);
    printf("Fast wait time: %d ms\n", termkey_get_waittime(tk));

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### termkey_push_bytes - Supply bytes directly

Source: https://context7.com/o11c/libtermkey/llms.txt

Pushes bytes directly into the termkey buffer for parsing, useful when bytes come from sources other than a file descriptor.

```APIDOC
## termkey_push_bytes - Supply bytes directly

### Description
Pushes bytes directly into the termkey buffer for parsing, useful when bytes come from sources other than a file descriptor.

### Method
POST (Conceptual - this is a library function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bytes** (const char*) - Pointer to the byte array to push.
- **num_bytes** (size_t) - The number of bytes to push.

### Request Example
```c
#include <termkey.h>
#include <stdio.h>
#include <string.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key;
    char buffer[50];

    // Simulate receiving escape sequences
    const char *sequences[] = {
        "\x1b[A",       // Up arrow
        "\x1b[B",       // Down arrow
        "\x1b[1;5C",    // Ctrl-Right
        "hello",        // Regular text
        "\x1b[M !\"",   // Mouse click at (1,2)
    };

    for (int i = 0; i < 5; i++) {
        size_t len = strlen(sequences[i]);
        termkey_push_bytes(tk, sequences[i], len);

        while (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
            termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
            printf("Parsed: %s\n", buffer);
        }
    }
    // Output:
    // Parsed: <Up>
    // Parsed: <Down>
    // Parsed: <C-Right>
    // Parsed: h
    // Parsed: e
    // Parsed: l
    // Parsed: l
    // Parsed: o
    // Parsed: <M1>

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response
(No explicit return value indicating success, operation is performed in-place)

#### Response Example
(See C code example for output format)
```

--------------------------------

### termkey_waitkey - Synchronous blocking key read

Source: https://context7.com/o11c/libtermkey/llms.txt

Blocks until a complete key event is available, automatically handling multi-byte sequences and timeouts. This is the simplest method for reading keys in a synchronous application.

```APIDOC
## termkey_waitkey - Synchronous blocking key read

### Description
Blocks until a complete key event is available, handling multi-byte sequences and timeouts automatically. This is the simplest way to read keys in a synchronous application.

### Method
`termkey_waitkey`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include <termkey.h>
#include <stdio.h>
#include <errno.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, TERMKEY_FLAG_CTRLC);
    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    char buffer[50];
    TermKeyKey key;
    TermKeyResult ret;

    printf("Press keys (Ctrl-C to exit):\n");

    while ((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
        if (ret == TERMKEY_RES_KEY) {
            termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
            printf("Key: %s\n", buffer);

            // Exit on Ctrl-C
            if (key.type == TERMKEY_TYPE_UNICODE &&
                key.modifiers & TERMKEY_KEYMOD_CTRL &&
                (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
                break;
        }
        else if (ret == TERMKEY_RES_ERROR) {
            if (errno != EINTR) {
                perror("termkey_waitkey");
                break;
            }
            printf("Interrupted by signal\n");
        }
    }

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
Returns `TERMKEY_RES_KEY` if a key event is successfully read, `TERMKEY_RES_EOF` if the end of file is reached, or `TERMKEY_RES_ERROR` if an error occurs.

#### Response Example
(See C code example for usage)
```

--------------------------------

### Synchronous Blocking Key Read with termkey_waitkey

Source: https://context7.com/o11c/libtermkey/llms.txt

Blocks until a complete key event is available, automatically handling multi-byte sequences and timeouts. This is the simplest method for synchronous key reading. Handles EOF and errors, including interruptions by signals.

```c
#include <termkey.h>
#include <stdio.h>
#include <errno.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, TERMKEY_FLAG_CTRLC);
    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    char buffer[50];
    TermKeyKey key;
    TermKeyResult ret;

    printf("Press keys (Ctrl-C to exit):\n");

    while ((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
        if (ret == TERMKEY_RES_KEY) {
            termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
            printf("Key: %s\n", buffer);

            // Exit on Ctrl-C
            if (key.type == TERMKEY_TYPE_UNICODE &&
                key.modifiers & TERMKEY_KEYMOD_CTRL &&
                (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
                break;
        }
        else if (ret == TERMKEY_RES_ERROR) {
            if (errno != EINTR) {
                perror("termkey_waitkey");
                break;
            }
            printf("Interrupted by signal\n");
        }
    }

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### termkey_new_abstract - Create instance without file handle

Source: https://context7.com/o11c/libtermkey/llms.txt

Creates a termkey instance not connected to any file descriptor. This is useful for parsing terminal bytes from other sources such as network connections or recorded input.

```APIDOC
## termkey_new_abstract - Create instance without file handle

### Description
Creates a termkey instance not connected to any file descriptor, useful for parsing terminal bytes from other sources like network connections or recorded input.

### Method
`termkey_new_abstract`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    // Create abstract instance for xterm-256color terminal type
    TermKey *tk = termkey_new_abstract("xterm-256color", 0);

    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    // Push bytes manually instead of reading from file descriptor
    const char input[] = "\x1b[A";  // Up arrow escape sequence
    termkey_push_bytes(tk, input, sizeof(input) - 1);

    TermKeyKey key;
    if (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
        char buffer[50];
        termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_VIM);
        printf("Parsed key: %s\n", buffer);  // Output: <Up>
    }

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
Returns a pointer to a `TermKey` instance on success.

#### Response Example
(See C code example for usage)
```

--------------------------------

### Convert Key Symbol to Name and Vice Versa

Source: https://context7.com/o11c/libtermkey/llms.txt

Converts between symbolic key values (TermKeySym) and their string names. This is useful for configuration files or debugging purposes. Ensure a TermKey instance is created before calling these functions.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);

    // Get name from symbol
    const char *name = termkey_get_keyname(tk, TERMKEY_SYM_UP);
    printf("TERMKEY_SYM_UP is named: %s\n", name);  // "Up"

    name = termkey_get_keyname(tk, TERMKEY_SYM_PAGEDOWN);
    printf("TERMKEY_SYM_PAGEDOWN is named: %s\n", name);  // "PageDown"

    // Get symbol from name
    TermKeySym sym = termkey_keyname2sym(tk, "Home");
    printf("'Home' has symbol value: %d (TERMKEY_SYM_HOME=%d)\n",
           sym, TERMKEY_SYM_HOME);

    sym = termkey_keyname2sym(tk, "Delete");
    printf("'Delete' has symbol value: %d\n", sym);

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### termkey_getkey - Non-blocking key retrieval

Source: https://context7.com/o11c/libtermkey/llms.txt

Retrieves a key event from the internal buffer without blocking. Returns TERMKEY_RES_NONE if no complete key is available, TERMKEY_RES_AGAIN if a partial sequence was detected.

```APIDOC
## termkey_getkey - Non-blocking key retrieval

### Description
Retrieves a key event from the internal buffer without blocking. Returns `TERMKEY_RES_NONE` if no complete key is available, `TERMKEY_RES_AGAIN` if a partial sequence was detected.

### Method
GET (Conceptual - this is a library function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include <termkey.h>
#include <poll.h>
#include <stdio.h>

static void on_key(TermKey *tk, TermKeyKey *key)
{
    char buffer[50];
    termkey_strfkey(tk, buffer, sizeof buffer, key, TERMKEY_FORMAT_VIM);
    printf("%s\n", buffer);
}

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    if (!tk) {
        fprintf(stderr, "Cannot allocate termkey instance\n");
        return 1;
    }

    struct pollfd fd;
    fd.fd = 0;
    fd.events = POLLIN;

    TermKeyResult ret;
    TermKeyKey key;
    int running = 1;
    int nextwait = -1;

    while (running) {
        if (poll(&fd, 1, nextwait) == 0) {
            // Timeout - force interpretation of partial sequence
            if (termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
                on_key(tk, &key);
        }

        if (fd.revents & (POLLIN | POLLHUP | POLLERR))
            termkey_advisereadable(tk);

        // Process all available keys
        while ((ret = termkey_getkey(tk, &key)) == TERMKEY_RES_KEY) {
            on_key(tk, &key);

            // Exit on Ctrl-C
            if (key.type == TERMKEY_TYPE_UNICODE &&
                key.modifiers & TERMKEY_KEYMOD_CTRL &&
                (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
                running = 0;
        }

        if (ret == TERMKEY_RES_AGAIN)
            nextwait = termkey_get_waittime(tk);
        else
            nextwait = -1;
    }

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (TERMKEY_RES_KEY)
- **key** (TermKeyKey) - A complete key event has been parsed.

#### Success Response (TERMKEY_RES_NONE)
No complete key is available in the buffer.

#### Success Response (TERMKEY_RES_AGAIN)
A partial sequence was detected, and more input is needed.

#### Response Example
(See C code example for output format)
```

--------------------------------

### Parse String to Key Event

Source: https://context7.com/o11c/libtermkey/llms.txt

Parses a string representation of a key into a TermKeyKey structure. This is useful for configuration parsing or keybinding definitions. The function returns the remaining unparsed string, or NULL on failure.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);
    TermKeyKey key;

    // Parse various key representations
    const char *keystrings[] = {
        "C-a",          // Ctrl-A
        "S-Up",         // Shift-Up
        "M-x",          // Alt-x (Meta-x)
        "F5",           // Function key 5
        "C-S-Delete",   // Ctrl-Shift-Delete
        "Space",        // Space key
    };

    for (int i = 0; i < 6; i++) {
        const char *remaining = termkey_strpkey(tk, keystrings[i], &key, TERMKEY_FORMAT_VIM);

        if (remaining) {
            char buffer[50];
            termkey_strfkey(tk, buffer, sizeof buffer, &key, TERMKEY_FORMAT_LONGMOD);
            printf("Parsed '%s' -> type=%d, mods=%d, formatted='%s'\n",
                   keystrings[i], key.type, key.modifiers, buffer);
        } else {
            printf("Failed to parse: %s\n", keystrings[i]);
        }
    }

    termkey_destroy(tk);
    return 0;
}

```

--------------------------------

### termkey_get_keyname / termkey_keyname2sym - Symbol name conversion

Source: https://context7.com/o11c/libtermkey/llms.txt

Converts between symbolic key values and their string names, useful for configuration and debugging.

```APIDOC
## termkey_get_keyname / termkey_keyname2sym - Symbol name conversion

### Description
Converts between symbolic key values and their string names, useful for configuration and debugging.

### Method
(Not applicable, these are function calls within a C program)

### Endpoint
(Not applicable)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new_abstract("xterm", 0);

    // Get name from symbol
    const char *name = termkey_get_keyname(tk, TERMKEY_SYM_UP);
    printf("TERMKEY_SYM_UP is named: %s\n", name);  // "Up"

    name = termkey_get_keyname(tk, TERMKEY_SYM_PAGEDOWN);
    printf("TERMKEY_SYM_PAGEDOWN is named: %s\n", name);  // "PageDown"

    // Get symbol from name
    TermKeySym sym = termkey_keyname2sym(tk, "Home");
    printf("'Home' has symbol value: %d (TERMKEY_SYM_HOME=%d)\n",
           sym, TERMKEY_SYM_HOME);

    sym = termkey_keyname2sym(tk, "Delete");
    printf("'Delete' has symbol value: %d\n", sym);

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
(Not applicable, these are functions that return values or modify variables)

#### Response Example
(See Request Example for output format)
```

--------------------------------

### termkey_advisereadable - Notify of available input

Source: https://context7.com/o11c/libtermkey/llms.txt

Informs the termkey instance that more bytes may be available on the file descriptor. Should be called when poll/select indicates the fd is readable.

```APIDOC
## termkey_advisereadable - Notify of available input

### Description
Informs the termkey instance that more bytes may be available on the file descriptor. Should be called when poll/select indicates the fd is readable.

### Method
GET (Conceptual - this is a library function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include <termkey.h>
#include <poll.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    struct pollfd pfd = { .fd = 0, .events = POLLIN };

    while (1) {
        poll(&pfd, 1, -1);

        if (pfd.revents & POLLIN) {
            // Tell termkey to read available bytes
            TermKeyResult res = termkey_advisereadable(tk);

            if (res == TERMKEY_RES_AGAIN) {
                // Bytes were read, process keys
                TermKeyKey key;
                while (termkey_getkey(tk, &key) == TERMKEY_RES_KEY) {
                    char buf[50];
                    termkey_strfkey(tk, buf, sizeof buf, &key, TERMKEY_FORMAT_VIM);
                    printf("Key: %s\n", buf);
                }
            }
        }
    }

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (TERMKEY_RES_AGAIN)
- **res** (TermKeyResult) - Indicates that bytes were read and should be processed.

#### Success Response (Other)
Indicates no new bytes were read or an error occurred.

#### Response Example
(See C code example for output format)
```

--------------------------------

### termkey_set_waittime / termkey_get_waittime - Timeout configuration

Source: https://context7.com/o11c/libtermkey/llms.txt

Controls the timeout for multi-byte sequence completion. When a partial escape sequence is detected, termkey waits this many milliseconds for more bytes before interpreting what's available.

```APIDOC
## termkey_set_waittime / termkey_get_waittime - Timeout configuration

### Description
Controls the timeout for multi-byte sequence completion. When a partial escape sequence is detected, termkey waits this many milliseconds for more bytes before interpreting what's available.

### Method
(Not applicable, these are function calls within a C program)

### Endpoint
(Not applicable)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);

    // Get default wait time (usually 50ms)
    int waittime = termkey_get_waittime(tk);
    printf("Default wait time: %d ms\n", waittime);

    // Increase for high-latency connections (e.g., SSH)
    termkey_set_waittime(tk, 100);
    printf("New wait time: %d ms\n", termkey_get_waittime(tk));

    // Decrease for local, responsive terminals
    termkey_set_waittime(tk, 20);
    printf("Fast wait time: %d ms\n", termkey_get_waittime(tk));

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
(Not applicable, these are functions that return values or modify variables)

#### Response Example
(See Request Example for output format)
```

--------------------------------

### Interpret Cursor Position Event

Source: https://context7.com/o11c/libtermkey/llms.txt

Use this function to parse a cursor position report event, typically received after a "Report Cursor Position" escape sequence. Ensure a TermKey instance is initialized and a position event is captured before calling.

```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    if (!tk) return 1;

    // Request cursor position (DEC CPR)
    printf("\033[?6n");
    fflush(stdout);

    TermKeyKey key;

    while (termkey_waitkey(tk, &key) == TERMKEY_RES_KEY) {
        if (key.type == TERMKEY_TYPE_POSITION) {
            int line, col;
            termkey_interpret_position(tk, &key, &line, &col);
            printf("Cursor position: line=%d, column=%d\n", line, col);
            break;
        }
    }

    termkey_destroy(tk);
    return 0;
}
```

--------------------------------

### termkey_interpret_position - Extract cursor position

Source: https://context7.com/o11c/libtermkey/llms.txt

Interprets a cursor position report event, typically received in response to a "Report Cursor Position" escape sequence.

```APIDOC
## termkey_interpret_position - Extract cursor position

### Description
Interprets a cursor position report event, typically received in response to a "Report Cursor Position" escape sequence.

### Method
(Not applicable, this is a function call within a C program)

### Endpoint
(Not applicable)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <termkey.h>
#include <stdio.h>

int main(void)
{
    TERMKEY_CHECK_VERSION;

    TermKey *tk = termkey_new(0, 0);
    if (!tk) return 1;

    // Request cursor position (DEC CPR)
    printf("\033[?6n");
    fflush(stdout);

    TermKeyKey key;

    while (termkey_waitkey(tk, &key) == TERMKEY_RES_KEY) {
        if (key.type == TERMKEY_TYPE_POSITION) {
            int line, col;
            termkey_interpret_position(tk, &key, &line, &col);
            printf("Cursor position: line=%d, column=%d\n", line, col);
            break;
        }
    }

    termkey_destroy(tk);
    return 0;
}
```

### Response
#### Success Response (200)
(Not applicable, this is a function that modifies variables passed by pointer)

#### Response Example
(See Request Example for output format)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.