### Example: Print keypress details until Ctrl-C

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_waitkey.3.html

This example program utilizes termkey_waitkey to capture and display details of every keypress. It includes options for enabling mouse support and specific mouse protocols. The loop terminates when the user presses Ctrl-C.

```c
#define _XOPEN_SOURCE 600

#include <stdio.h>
#include <unistd.h>
#include <errno.h>

#include "termkey.h"

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

  int mouse = 0;
  int mouse_proto = 0;
  TermKeyFormat format = TERMKEY_FORMAT_VIM;

  char buffer[50];
  TermKey *tk;

  int opt;
  while((opt = getopt(argc, argv, "m::p:")) != -1) {
    switch(opt) {
    case 'm':
      if(optarg)
        mouse = atoi(optarg);
      else
        mouse = 1000;

      break;

    case 'p':
      mouse_proto = atoi(optarg);
      break;

    default:
      fprintf(stderr, "Usage: %s [-m]\n", argv[0]);
      return 1;
    }
  }

  tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL|TERMKEY_FLAG_CTRLC);

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

  TermKeyResult ret;
  TermKeyKey key;

  if(mouse) {
    printf("\033[?%dhMouse mode active\n", mouse);
    if(mouse_proto)
      printf("\033[?%dh", mouse_proto);
  }

  while((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
    if(ret == TERMKEY_RES_KEY) {
      termkey_strfkey(tk, buffer, sizeof buffer, &key, format);
      if(key.type == TERMKEY_TYPE_MOUSE) {
        int line, col;
        termkey_interpret_mouse(tk, &key, NULL, NULL, &line, &col);
        printf("%s at line=%d, col=%d\n", buffer, line, col);
      }
      else if(key.type == TERMKEY_TYPE_POSITION) {
        int line, col;
        termkey_interpret_position(tk, &key, &line, &col);
        printf("Cursor position report at line=%d, col=%d\n", line, col);
      }
      else if(key.type == TERMKEY_TYPE_MODEREPORT) {
        int initial, mode, value;
        termkey_interpret_modereport(tk, &key, &initial, &mode, &value);
        printf("Mode report %s mode %d = %d\n", initial ? "DEC" : "ANSI", mode, value);
      }
      else if(key.type == TERMKEY_TYPE_UNKNOWN_CSI) {
        long args[16];
        size_t nargs = 16;
        unsigned long command;
        termkey_interpret_csi(tk, &key, args, &nargs, &command);
        printf("Unrecognised CSI %c %ld;%ld %c%c\n", (char)(command >> 8), args[0], args[1], (char)(command >> 16), (char)command);
      }
      else {
        printf("%s\n", buffer);
      }

      if(key.type == TERMKEY_TYPE_UNICODE &&
         key.modifiers & TERMKEY_KEYMOD_CTRL &&
         (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
        break;

      if(key.type == TERMKEY_TYPE_UNICODE &&
         key.modifiers == 0 &&
         key.code.codepoint == '?') {
        // printf("\033[?6n"); // DECDSR 6 == request cursor position
        printf("\033[?1$p"); // DECRQM == request mode, DEC origin mode
        fflush(stdout);
      }
    }
    else if(ret == TERMKEY_RES_ERROR) {
      if(errno != EINTR) {
        perror("termkey_waitkey");
        break;
      }
      printf("Interrupted by signal\n");
    }
  }

  if(mouse)
    printf("\033[?%dlMouse mode deactivated\n", mouse);

  termkey_destroy(tk);
}

```

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

### Example: Asynchronous keypress handling with poll(2)

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_getkey.3.html

Demonstrates using termkey_getkey and termkey_getkey_force within a poll(2)-driven asynchronous program. Handles keypresses, timed events, and checks for Ctrl-C to exit.

```c
#define _XOPEN_SOURCE 600

#include <poll.h>
#include <stdio.h>

#include "termkey.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(int argc, char *argv[])
{
  TERMKEY_CHECK_VERSION;

  TermKey *tk = termkey_new(0, 0);

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

  struct pollfd fd;

  fd.fd = 0; /* the file descriptor we passed to termkey_new() */
  fd.events = POLLIN;

  TermKeyResult ret;
  TermKeyKey key;

  int running = 1;
  int nextwait = -1;

  while(running) {
    if(poll(&fd, 1, nextwait) == 0) {
      // Timed out
      if(termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
        on_key(tk, &key);
    }

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

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

      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);
}
```

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

### Get TermKey Buffer Size

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_buffer_size.3.html

Returns the size of the buffer set by the last call to termkey_set_buffer_size(), or the default initial size of 256 bytes.

```c
#include <termkey.h>

size_t termkey_get_buffer_size(TermKey **_tk_);

```

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

### Get current wait time for multibyte sequences in termkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_waittime.3.html

Use termkey_get_waittime to retrieve the current wait time in milliseconds set by the last call to termkey_set_waittime. Returns the current wait time.

```c
#include <termkey.h>

int termkey_get_waittime(TermKey **_tk_);

```

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

### Demonstration Program for libtermkey

Source: http://www.leonerd.org.uk/code/libtermkey/overview.html

This program demonstrates the basic usage of libtermkey by initializing an instance, waiting for key presses, printing them, and breaking on Ctrl+C. It requires including the 'termkey.h' header.

```c
#include <stdio.h>

#include "termkey.h"

int main(int argc, char *argv[]) {
  char buffer[50];
  TermKey *tk = termkey_new(0, 0);

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

  TermKeyResult ret;
  TermKeyKey key;

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

    if(key.type == TERMKEY_TYPE_UNICODE &&
       key.modifiers & TERMKEY_KEYMOD_CTRL &&
       (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
      break;
  }

  termkey_destroy(tk);
}
```

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

### termkey_set_waittime

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_waittime.3.html

Sets the number of milliseconds termkey_waitkey will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.

```APIDOC
## termkey_set_waittime

### Description
Sets the number of miliseconds that termkey_waitkey(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.

### Signature
```c
void termkey_set_waittime(TermKey **_tk_, int _msec_);
```

### Parameters
#### Path Parameters
- **_tk_** (TermKey ***) - A pointer to the TermKey instance.
- **_msec_** (int) - The wait time in milliseconds.

### Return Value
This function returns no value.
```

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

### Initialize TermKey Instance

Source: http://www.leonerd.org.uk/code/libtermkey/overview.html

Constructs a new TermKey instance to wrap a file descriptor. The default flags (0) are usually sufficient.

```c
TermKey *termkey_new(int fd, int flags);
```

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

### Get Key Name from Symbolic Key

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_get_keyname.3.html

Use termkey_get_keyname to obtain a string representation of a symbolic key. The returned string is managed by the TermKey instance.

```c
const char *termkey_get_keyname(TermKey *_tk_, TermKeySym _sym_);
```

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

### Obtain Terminal File Descriptor

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_get_fd.3.html

Use termkey_get_fd() to get the file descriptor the termkey instance uses for reading. Returns -1 if no file descriptor is associated.

```c
#include <termkey.h>

int termkey_get_fd(TermKey **_tk_);

```

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

### Enable Terminal Operations with termkey_start

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_start.3.html

Use termkey_start to enable terminal IO operations, including sending control sequences and setting termios modes. A newly constructed TermKey instance has terminal IO enabled by default.

```c
#include <termkey.h>

int termkey_start(TermKey **_tk_);
```

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

### Create a New Termkey Instance with File Descriptor

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Use termkey_new() to create a termkey instance linked to a file descriptor. Ensure the file descriptor is valid and flags are set appropriately. Returns NULL on failure.

```c
TermKey *termkey_new(int *_fd_, int *_flags_);
```

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

### Get Termkey Operational Flags

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_flags.3.html

Use termkey_get_flags to retrieve the current operational flags of a TermKey instance. This returns the value set by the last call to termkey_set_flags or the constructor.

```c
#include <termkey.h>

int termkey_get_flags(TermKey **_tk_);

```

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

### Create an Abstract Termkey Instance

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Use termkey_new_abstract() to create a termkey instance without a file descriptor, useful for abstract input sources. Specify the termtype string and flags. Returns NULL on failure.

```c
TermKey *termkey_new_abstract(const char **_term_, int *_flags_);
```

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

### Get Remaining Buffer Space

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_get_buffer_remaining.3.html

Returns the number of free bytes in the termkey buffer. This is useful for managing buffer capacity before pushing new bytes or when advising about readable data.

```c
#include <termkey.h>

size_t termkey_get_buffer_remaining(TermKey *_tk_);

```

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

### Format Keypress to String

Source: http://www.leonerd.org.uk/code/libtermkey/overview.html

Formats a string buffer to contain a string description of the keypress, similar to snprintf or strftime.

```c
size_t termkey_strfkey(TermKey *tk, char *buffer, size_t len,
                   TermKeyKey key, TermKeyFormat format);
```

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

### termkey_start, termkey_stop, termkey_is_started

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_start.3.html

These functions control the terminal IO operations for a termkey instance. termkey_start() enables operations, termkey_stop() disables them, and termkey_is_started() checks the current status. A new termkey instance has terminal IO enabled by default.

```APIDOC
## termkey_start, termkey_stop, termkey_is_started

### Description
Enables or disables terminal operations for a given termkey instance.

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

int termkey_start(TermKey **_tk_);
int termkey_stop(TermKey **_tk_);
int termkey_is_started(TermKey **_tk_);
```

### Details
- **termkey_start()**: Enables terminal IO operations, including sending control sequences and setting termios modes.
- **termkey_stop()**: Disables terminal IO operations by reversing the steps of termkey_start().
- **termkey_is_started()**: Checks if terminal IO is currently enabled.

### Return Value
- **termkey_start()**, **termkey_stop()**: Return true on success, zero on failure (with errno set).
- **termkey_is_started()**: Returns true if terminal IO is enabled, false otherwise.

### Linking
Link with -ltermkey.
```

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

### Include Termkey Header

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_keycmp.3.html

Include the termkey header file to use the termkey_keycmp function. This is a prerequisite for using any termkey functions.

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

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

### termkey_start, termkey_stop, termkey_is_started

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Enables or disables terminal operations.

```APIDOC
## termkey_start, termkey_stop, termkey_is_started

### Description
Enable or disable terminal operations.

### Method
APIDOC

### Endpoint
termkey_start, termkey_stop, termkey_is_started

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### Push Bytes into TermKey Input Buffer

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_push_bytes.3.html

Use termkey_push_bytes to supply raw bytes directly into the TermKey input buffer. This is essential when TermKey does not read from a standard file handle. Ensure sufficient buffer space is available to avoid ENOMEM errors.

```c
size_t termkey_push_bytes(TermKey *_tk_, const char *_bytes_, size_t _len_);

```

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

### Include Header for TermKey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_push_bytes.3.html

Include the termkey header file to use the termkey_push_bytes function. This is a prerequisite for any termkey operations.

```c
#include <termkey.h>

```

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

### Version Check Macro for Termkey Library

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Applications must use TERMKEY_CHECK_VERSION macro early in main() to ensure library compatibility.

```c
TERMKEY_CHECK_VERSION;
```

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

### termkey_advisereadable

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Advises to read more bytes from the underlying terminal.

```APIDOC
## termkey_advisereadable

### Description
Read more bytes from the underlying terminal.

### Method
APIDOC

### Endpoint
termkey_advisereadable

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### Retrieve next key event with termkey_getkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_getkey.3.html

Attempts to retrieve a single keypress event from the termkey instance buffer. Returns TERMKEY_RES_KEY on success, TERMKEY_RES_AGAIN if a partial event is found, TERMKEY_RES_NONE if no bytes are waiting, TERMKEY_RES_EOF if the input stream is closed, or TERMKEY_RES_ERROR if IO is stopped.

```c
#include <termkey.h>

TermKeyResult termkey_getkey(TermKey *_tk_, TermKeyKey *_key_);
```

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

### termkey_new

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Creates a new termkey instance connected to a file descriptor with specified flags.

```APIDOC
## termkey_new

### Description

Creates a new termkey instance connected to the file handle opened by _fd_ using the _flags_. The TermKey structure should be considered opaque; its contents are not intended for use outside of the library. The constructor attempts to detect if the current locale is UTF-8 aware or not, and sets either the TERMKEY_FLAG_UTF8 or TERMKEY_FLAG_RAW flag. One of these two bits will always be in effect. If a file handle is provided, the terminfo driver may send a string to initialise or set the state of the terminal before termkey_new() returns. This will not be done if no file handle is provided, or if the file handle is a pipe (S_ISFIFO()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode.

### Synopsis

```c
#include <termkey.h>

TermKey *termkey_new(int **_fd_**, int **_flags_**);
```

### Parameters

*   **_fd_** (int **) - A pointer to the file descriptor for the terminal.
*   **_flags_** (int *) - Flags to configure the termkey instance.

### Return Value

If successful, termkey_new() returns a pointer to the new instance. On failure, NULL is returned with _errno_ set to indicate the failure.

### Errors

*   **ENOENT**: No driver was able to recognise the given terminal type.
*   **ENOMEM**: A call to malloc(3) failed to allocate memory.

Additionally, termkey_new() may fail if fstat(2) or write(2) fails on the given file handle.
```

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

### termkey_getkey and termkey_getkey_force

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_getkey.3.html

These functions attempt to retrieve a single key press event from the TermKey instance buffer. termkey_getkey may return TERMKEY_RES_AGAIN for partial events, while termkey_getkey_force will interpret partial events by forcing an interpretation. Neither function blocks or performs IO.

```APIDOC
## termkey_getkey and termkey_getkey_force

### Description
Attempts to retrieve a single keypress event from the TermKey instance buffer and place it in the provided structure. `termkey_getkey_force` differs by not returning `TERMKEY_RES_AGAIN` for partial events, instead forcing an interpretation.

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

TermKeyResult termkey_getkey(TermKey *_tk_, TermKeyKey *_key_);
TermKeyResult termkey_getkey_force(TermKey *_tk_, TermKeyKey *_key_);
```

### Return Value
Returns an enumeration indicating the result:
- **TERMKEY_RES_KEY**: A complete keypress was retrieved.
- **TERMKEY_RES_AGAIN**: A partial keypress event was found (only for `termkey_getkey`).
- **TERMKEY_RES_NONE**: No bytes are waiting in the buffer.
- **TERMKEY_RES_EOF**: No bytes are ready and the input stream is closed.
- **TERMKEY_RES_ERROR**: Terminal IO was stopped.

### Example
```c
// <poll.h> might need this for sigset_t
#define _XOPEN_SOURCE 600

#include <poll.h>
#include <stdio.h>

#include "termkey.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(int argc, char *argv[])
{
  TERMKEY_CHECK_VERSION;

  TermKey *tk = termkey_new(0, 0);

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

  struct pollfd fd;

  fd.fd = 0; /* the file descriptor we passed to termkey_new() */
  fd.events = POLLIN;

  TermKeyResult ret;
  TermKeyKey key;

  int running = 1;
  int nextwait = -1;

  while(running) {
    if(poll(&fd, 1, nextwait) == 0) {
      // Timed out
      if(termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
        on_key(tk, &key);
    }

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

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

      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);
}

```

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

### TERMKEY_CHECK_VERSION

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Macro to check library version compatibility. Should be called early in the application's main function.

```APIDOC
## TERMKEY_CHECK_VERSION

### Description

Before calling any functions in the termkey library, an application should use the TERMKEY_CHECK_VERSION macro to check that the loaded version of the library is compatible with the version it was compiled against. This should be done early on, ideally just after entering its main() function.

### Usage

```c
#include <termkey.h>

TERMKEY_CHECK_VERSION;
```
```

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

### termkey_waitkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Waits for and retrieves the next key event.

```APIDOC
## termkey_waitkey

### Description
Wait for and retrieve the next key event.

### Method
APIDOC

### Endpoint
termkey_waitkey

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### Interpreting CSI Command Structure

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_interpret_csi.3.html

This C code snippet illustrates how the command, initial byte, and intermediate byte are combined into a single unsigned long value. The initial byte is shifted by 8 bits, and the intermediate byte by 16 bits, before being bitwise OR-ed with the command.

```c
*cmd = command | (initial << 8) | (intermediate << 16);

```

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

### Declare Termkey Advisereadable Function

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_advisereadable.3.html

Declare the termkey_advisereadable function signature. Link with -ltermkey.

```c
TermKeyResult termkey_advisereadable(TermKey **_tk_);
```

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

### termkey_lookup_keyname Function Signature

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_lookup_keyname.3.html

Include the termkey header to use this function. It takes a double pointer to TermKey, a constant character pointer for the key name, and a pointer to TermKeySym to store the result. Link with -ltermkey.

```c
#include <termkey.h>

char *termkey_lookup_keyname(TermKey **_tk_, const char **_keyname_,
           TermKeySym *_sym_);
```

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

### termkey_keycmp

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Compares two key events.

```APIDOC
## termkey_keycmp

### Description
Compare two key events.

### Method
APIDOC

### Endpoint
termkey_keycmp

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_waitkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_waitkey.3.html

Waits for and retrieves the next key event. If successful, it returns TERMKEY_RES_KEY. If the buffer is empty, it blocks until a key is available. It returns TERMKEY_RES_EOF if the input stream is closed and TERMKEY_RES_ERROR if an IO error occurs.

```APIDOC
## termkey_waitkey

### Description
Waits for and retrieves the next key event from the termkey instance buffer, storing it in the provided TermKeyKey structure. It returns TERMKEY_RES_KEY on success, TERMKEY_RES_EOF if the input stream is closed, and TERMKEY_RES_ERROR on IO errors.

### Function Signature
```c
TermKeyResult termkey_waitkey(TermKey **_tk_, TermKeyKey **_key_);
```

### Parameters
- **_tk_** (TermKey **): A pointer to the TermKey instance.
- **_key_** (TermKeyKey **): A pointer to a TermKeyKey structure where the key event will be stored.

### Return Value
- **TERMKEY_RES_KEY**: A key event has been provided.
- **TERMKEY_RES_EOF**: No key events are ready and the terminal has been closed.
- **TERMKEY_RES_ERROR**: An IO error occurred. _errno_ will be preserved.

### Notes
- Before returning, this function canonicalizes the _key_ structure.
- It attempts to wait for multibyte sequences to complete, with a configurable timeout set by termkey_set_waittime(3).
- If the TERMKEY_FLAG_EINTR flag is set, EINTR errors will cause the operation to be retried.
- If called after termkey_stop(3), _errno_ will be set to EINVAL.
```

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

### Check if Terminal Operations are Enabled with termkey_is_started

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_start.3.html

Use termkey_is_started to enquire whether terminal IO operations are currently enabled for a TermKey instance. It returns true if enabled, false otherwise.

```c
#include <termkey.h>

int termkey_is_started(TermKey **_tk_);
```

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

### termkey_keyname2sym

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_keyname2sym.3.html

The termkey_keyname2sym() function looks up the symbolic key value represented by the given string name. It performs a case-sensitive comparison. If the name is not found, TERMKEY_SYM_UNKNOWN is returned. This function is the inverse of termkey_get_keyname(3) and a more specific version of termkey_lookup_keyname(3). Due to its linear search nature, it's recommended for use during program initialization.

```APIDOC
## NAME
termkey_keyname2sym - look up a symbolic key value for a string name

## SYNOPSIS
```c
**#include <termkey.h>** 
**TermKeySym termkey_keyname2sym(TermKey ***_tk_**, const char ***_keyname_**);
```

Link with _-ltermkey_.

## DESCRIPTION
**termkey_keyname2sym**() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. If the given name is not found, **TERMKEY_SYM_UNKNOWN** is returned instead. This function is the inverse of **termkey_get_keyname**(3), and is a more specific form of **termkey_lookup_keyname**(3) which only recognises names as complete strings.
Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running.

## RETURN VALUE
**termkey_keyname2sym**() returns a symbolic key constant, or **TERMKEY_SYM_UNKNOWN**.

## SEE ALSO
**termkey_get_keyname**(3), **termkey_lookup_keyname**(3), **termkey_strpkey**(3), **termkey**(7)
```

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

### termkey_getkey, termkey_getkey_force

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Retrieves the next key event.

```APIDOC
## termkey_getkey, termkey_getkey_force

### Description
Retrieve the next key event.

### Method
APIDOC

### Endpoint
termkey_getkey, termkey_getkey_force

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_new_abstract

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_new.3.html

Creates a new termkey instance without an associated file handle, suitable for abstract input sources.

```APIDOC
## termkey_new_abstract

### Description

Creates a new termkey() instance with no file handle associated. As this is usually done for handling other sources of terminal byte input, it also takes a string indicating the termtype to use. The constructor attempts to detect if the current locale is UTF-8 aware or not, and sets either the TERMKEY_FLAG_UTF8 or TERMKEY_FLAG_RAW flag. One of these two bits will always be in effect.

### Synopsis

```c
#include <termkey.h>

TermKey *termkey_new_abstract(const char ***_term_**, int **_flags_**);
```

### Parameters

*   **_term_** (const char ***) - A string indicating the termtype to use.
*   **_flags_** (int *) - Flags to configure the termkey instance.

### Return Value

If successful, termkey_new_abstract() returns a pointer to the new instance. On failure, NULL is returned with _errno_ set to indicate the failure.

### Errors

*   **ENOENT**: No driver was able to recognise the given terminal type.
*   **ENOMEM**: A call to malloc(3) failed to allocate memory.
```

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

### Termkey Keyname to Symbol Lookup Function Signature

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_keyname2sym.3.html

This C function signature shows how to use termkey_keyname2sym to convert a key name string to a symbolic key value. Ensure you link with -ltermkey.

```c
#include <termkey.h>

TermKeySym termkey_keyname2sym(TermKey **_tk_, const char **_keyname_);

```

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

### Retrieve next key event with termkey_getkey_force

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_getkey.3.html

Similar to termkey_getkey, but forces an interpretation of partial events instead of returning TERMKEY_RES_AGAIN. This can lead to Escape-prefixed sequences being interpreted as literal Escape keys.

```c
#include <termkey.h>

TermKeyResult termkey_getkey_force(TermKey *_tk_, TermKeyKey *_key_);
```

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

### Function Signature for termkey_waitkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_waitkey.3.html

The function signature for termkey_waitkey. It takes a pointer to a TermKey instance and a pointer to a TermKeyKey structure to store the key event. It returns a TermKeyResult indicating the outcome.

```c
TermKeyResult termkey_waitkey(TermKey *_tk_, TermKeyKey *_key_);
```

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

### termkey_strpkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Parses a string representing a key event.

```APIDOC
## termkey_strpkey

### Description
Parse a string representing a key event.

### Method
APIDOC

### Endpoint
termkey_strpkey

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_keycmp

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_keycmp.3.html

Compares two key structures and applies a total ordering. Copies of both referenced structures are taken and canonicalised before comparison. Two structures of differing type are ordered by TERMKEY_TYPE_UNICODE, TERMKEY_TYPE_KEYSYM, TERMKEY_TYPE_FUNCTION, TERMKEY_TYPE_MOUSE. Within these values, keys different in modifier bits are ordered by the modifiers.

```APIDOC
## termkey_keycmp

### Description
Compares two key structures and applies a total ordering, returning a value that is negative, zero, or positive, to indicate if the given structures are increasing, identical, or decreasing. Before comparison, copies of both referenced structures are taken, and canonicalised according to the rules for termkey_canonicalise(3).

Two structures of differing type are ordered TERMKEY_TYPE_UNICODE , TERMKEY_TYPE_KEYSYM , TERMKEY_TYPE_FUNCTION , TERMKEY_TYPE_MOUSE. Unicode structures are ordered by codepoint, keysym structures are ordered by keysym number, function structures are ordered by function key number, and mouse structures are ordered opaquely by an unspecified but consistent ordering. Within these values, keys different in modifier bits are ordered by the modifiers.

### Parameters
- **_tk_** (TermKey ***) - A pointer to the TermKey instance.
- **_key1_** (const TermKeyKey ***) - A pointer to the first key structure to compare.
- **_key2_** (const TermKeyKey ***) - A pointer to the second key structure to compare.

### Return Value
An integer greater than, equal to, or less than zero to indicate the relation between the two given key structures.
```

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

### termkey_waitkey

Source: http://www.leonerd.org.uk/code/libtermkey/overview.html

Synchronously waits for and retrieves a key press from the terminal. The details of the key press are stored in the provided TermKeyKey structure.

```APIDOC
## termkey_waitkey

### Description
Synchronously block on terminal input, and return as soon as a key is pressed. Details of the keypress will be put in the `key` structure provided.

### Signature
```c
TermKeyResult termkey_waitkey(TermKey *tk, TermKeyKey *key);
```

### Parameters
#### Path Parameters
- **tk** (TermKey *) - A pointer to the TermKey instance.
- **key** (TermKeyKey *) - A pointer to a TermKeyKey structure to store the key press details.

### Return Value
- **TermKeyResult** - Indicates the result of the operation (e.g., key pressed, EOF).

### Key Structure
```c
typedef struct {
    TermKeyType type;
    union {
        long       codepoint; /* TERMKEY_TYPE_UNICODE  */
        int        number;    /* TERMKEY_TYPE_FUNCTION */
        TermKeySym sym;       /* TERMKEY_TYPE_KEYSYM   */
        char       mouse[4];  /* TERMKEY_TYPE_MOUSE
                                 opaque. see termkey_interpret_mouse */
    } code;
    int modifiers;
    char utf8[7];
} TermKeyKey;
```
```

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

### termkey_set_buffer_size, termkey_get_buffer_size

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Controls the buffer size.

```APIDOC
## termkey_set_buffer_size, termkey_get_buffer_size

### Description
Control the buffer size.

### Method
APIDOC

### Endpoint
termkey_set_buffer_size, termkey_get_buffer_size

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_interpret_csi

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_interpret_csi.3.html

Fills in variables according to the unrecognised CSI sequence event. It should be called if termkey_getkey or similar have returned a key event with the type of TERMKEY_TYPE_UNKNOWN_CSI. The _args_ array will be filled with the numerical arguments of the CSI sequence, and _cmd_ will contain the CSI command value.

```APIDOC
## NAME
termkey_interpret_csi - interpret unrecognised CSI sequence

## SYNOPSIS
```c
#include <termkey.h>
TermKeyResult termkey_interpret_csi(TermKey **_tk_, const TermKeyKey **_key_,
    long **_args_[], size_t **_nargs_**, unsigned long **_cmd_);**
```

Link with _-ltermkey_.

## DESCRIPTION
**termkey_interpret_csi**() fills in variables in the passed pointers according to the unrecognised CSI sequence event found in _key_. It should be called if **termkey_getkey**(3) or similar have returned a key event with the type of **TERMKEY_TYPE_UNKNOWN_CSI**. Note that it is important to call this function as soon as possible after obtaining a **TERMKEY_TYPE_CSI** key event; specifically, before calling **termkey_getkey**() or **termkey_waitkey**() again, as a subsequent call will overwrite the buffer space currently containing this sequence.
The _args_ array will be filled with the numerical arguments of the CSI sequence. The number of elements available in this array should be given as the initial value of the value pointed to by _nargs_ , which will be adjusted to give the number of arguments actually found when the function returns. The _cmd_ variable will contain the CSI command value. If a leading byte was found (such as '`?`') then it will be bitwise-ored with the command value, shifted up by 8 bits. If an intermediate byte was found (such as '`$`') then it will be bitwise-ored with the command value, shifted up by 16 bits.
```
    *cmd = command | (initial << 8) | (intermediate << 16);
```

## RETURN VALUE
If passed a _key_ event of the type **TERMKEY_TYPE_UNKNOWN_CSI** , this function will return **TERMKEY_RES_KEY** and will affect the variables whose pointers were passed in, as described above.
For other event types it will return **TERMKEY_RES_NONE** , and its effects on any variables whose pointers were passed in, are undefined.

## SEE ALSO
**termkey_waitkey**(3), **termkey_getkey**(3), **termkey**(7)
```

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

### termkey_strfkey Function

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_strfkey.3.html

Formats a key event into a human-readable string. The format argument is a bitmask of TERMKEY_FORMAT_* constants.

```APIDOC
## termkey_strfkey

### Description
Formats a string buffer to contain a human-readable representation of a key event. It fills the buffer in a way analogous to the snprintf(3) or strftime(3) standard library functions.

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

size_t termkey_strfkey(TermKey **_tk_, char **_buffer_**, size_t **_len_**, TermKeyKey ***_key_**, TermKeyFormat **_format_**);
```

### Parameters
*   **_tk_** (TermKey **) - A pointer to the TermKey instance.
*   **_buffer_** (char **) - The buffer to write the formatted string into.
*   **_len_** (size_t) - The size of the buffer.
*   **_key_** (TermKeyKey ***) - A pointer to the TermKeyKey structure representing the key event.
*   **_format_** (TermKeyFormat) - A bitmask of format flags to control the output string.

### Format Flags
*   **TERMKEY_FORMAT_LONGMOD**: Print full modifier names (e.g., "Shift-") instead of abbreviations.
*   **TERMKEY_FORMAT_CARETCTRL**: If the only modifier is Ctrl on a plain letter, render it as "^X" instead of "Ctrl-X".
*   **TERMKEY_FORMAT_ALTISMETA**: Use the name "Meta" or the letter "M" instead of "Alt" or "A".
*   **TERMKEY_FORMAT_WRAPBRACKET**: If the key event is a special key, wrap it in "<brackets>".
*   **TERMKEY_FORMAT_SPACEMOD**: Use spaces instead of hyphens to separate modifier names from the key name.
*   **TERMKEY_FORMAT_LOWERMOD**: Use lowercase for the modifier name.
*   **TERMKEY_FORMAT_LOWERSPACE**: Use lowercase with spaces for the key name (e.g., "page down" instead of "PageDown").
*   **TERMKEY_FORMAT_MOUSE_POS**: If the event is a mouse event, include the position rendered as "@ (col,line)".

### Shortcuts
*   **TERMKEY_FORMAT_VIM**: Shortcut for ALTISMETA and WRAPBRACKET.
*   **TERMKEY_FORMAT_URWID**: Shortcut for ALTISMETA, LONGMOD, LOWERMOD, SPACEMOD, and LOWERSPACE.

### Return Value
Returns the number of characters written to _buffer_.

### See Also
termkey_new(3), termkey_getkey(3), termkey_waitkey(3), termkey_get_keyname(3), termkey_strpkey(3), termkey(7)
```

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

### termkey_new, termkey_destroy

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Creates or destroys a new termkey instance.

```APIDOC
## termkey_new, termkey_destroy

### Description
Create or destroy a new termkey instance.

### Method
APIDOC

### Endpoint
termkey_new, termkey_destroy

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_get_fd

Source: http://www.leonerd.org.uk/code/libtermkey/doc

Obtains the file descriptor for the terminal.

```APIDOC
## termkey_get_fd

### Description
Obtain the file descriptor for the terminal.

### Method
APIDOC

### Endpoint
termkey_get_fd

### Parameters
None specified in source.

### Request Example
None specified in source.

### Response
#### Success Response (200)
None specified in source.

#### Response Example
None specified in source.
```

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

### termkey_advisereadable

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_advisereadable.3.html

Informs the termkey instance that new input may be available on the underlying file descriptor and so it should call read(2) to obtain it. If at least one more byte was read it will return TERMKEY_RES_AGAIN to indicate it may be useful to call termkey_getkey(3) again. If no more input was read then TERMKEY_RES_NONE is returned. If there was no buffer space remaining, then TERMKEY_RES_ERROR is returned with errno set to ENOMEM. If no filehandle is associated with this instance, TERMKEY_RES_ERROR is returned with errno set to EBADF.

```APIDOC
## termkey_advisereadable

### Description
Informs the termkey instance that new input may be available on the underlying file descriptor and so it should call read(2) to obtain it. If at least one more byte was read it will return TERMKEY_RES_AGAIN to indicate it may be useful to call termkey_getkey(3) again. If no more input was read then TERMKEY_RES_NONE is returned. If there was no buffer space remaining, then TERMKEY_RES_ERROR is returned with errno set to ENOMEM. If no filehandle is associated with this instance, TERMKEY_RES_ERROR is returned with errno set to EBADF.

### Method
```c
TermKeyResult termkey_advisereadable(TermKey **_tk_);
```

### Parameters
#### Path Parameters
* **_tk_** (TermKey **) - Required - A pointer to the TermKey instance.

### Return Value
**termkey_advisereadable**() returns one of the following constants:

**TERMKEY_RES_AGAIN**
    At least one byte was read.

**TERMKEY_RES_NONE**
    No nore bytes were read.

**TERMKEY_RES_ERROR**
    An IO error occured. _errno_ will be preserved. If the error is **EINTR** then this will only be returned if **TERMKEY_FLAG_EINTR** flag is not set; if it is then the IO operation will be retried instead.
```

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

### Set TermKey Buffer Size

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_buffer_size.3.html

Changes the size of the buffer space in the termkey instance. Pending bytes are preserved but truncated if the new size is smaller.

```c
#include <termkey.h>

int termkey_set_buffer_size(TermKey **_tk_, size_t _size_);

```

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

### termkey_strpkey

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_strpkey.3.html

Parses a string buffer containing a human-readable representation of a key event. It fills the _key_ structure from the results of this parsing, similar to the strptime(3) standard library function. The _format_ argument specifies the format expected in the string, as a bitmask of predefined constants.

```APIDOC
## termkey_strpkey

### Description
Parses a string buffer containing a human-readable representation of a key event. It fills the _key_ structure from the results of this parsing, similar to the **strptime**(3) standard library function.

The _format_ argument specifies the format expected in the string, as a bitmask of the following constants:

**TERMKEY_FORMAT_LONGMOD**
    Expect full modifier names e.g. "`Shift-`" instead of abbreviating to "`S-`". 

**TERMKEY_FORMAT_CARETCTRL**
    If the only modifier is **TERMKEY_MOD_CTRL** on a plain letter, accept it as "`^X`" rather than "`Ctrl-X`". 

**TERMKEY_FORMAT_ALTISMETA**
    Expect the name "`Meta`" or the letter "`M`" instead of "`Alt`" or "`A`". 

**TERMKEY_FORMAT_SPACEMOD**
    Expect spaces instead of hyphens to separate the modifer name(s) from the base key name. 

**TERMKEY_FORMAT_LOWERMOD**
    Expect lowercase for the modifier name. 

**TERMKEY_FORMAT_LOWERSPACE**
    Expect lowercase with spaces in for the key name instead of camelCase (for example "`page down`" instead of "`PageDown`").
Before returning, this function canonicalises the _key_ structure according to the rules given for **termkey_canonicalise**(3).
The **TERMKEY_FORMAT_WRAPBRACKET** and **TERMKEY_FORMAT_MOUSE_POS** options are currently not supported by **termkey_strpkey**(). When returning a **TERMKEY_TYPE_UNICODE** key structure, this function will fill in the _utf8_ member.

### Return Value
After a successful parse, **termkey_strpkey**() returns a pointer to the first character of the input it did not consume. If the input string contains more characters then this will point at the first character beyond. If the entire input string was consumed, then this will point at a null byte. If **termkey_strpkey**() fails to parse, it returns **NULL**. After a failed parse, the _key_ structure may contain partial or invalid results. The structure will only be valid if the function returns a non-**NULL** result.

### Synopsis
```c
char *termkey_strpkey(TermKey **_tk_**, const char **_str_**, TermKeyKey *_key_, TermKeyFormat _format_);
```

### See Also
**termkey_new**(3), **termkey_strfkey**(3), **termkey_keycmp**(3), **termkey**(7)
```

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

### Termkey Mouse Event Types

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_interpret_mouse.3.html

Defines the possible types of mouse events that can be interpreted.

```c
TERMKEY_MOUSE_UNKNOWN
    an unknown mouse event. 

TERMKEY_MOUSE_PRESS
    a mouse button was pressed; _button_ will contain its number. 

TERMKEY_MOUSE_DRAG
    the mouse was moved while holding a button; _button_ will contain its number. 

TERMKEY_MOUSE_RELEASE
    a mouse button was released, or the mouse was moved while no button was pressed. If known, _button_ will contain the number of the button released. Not all terminals can report this, so it may be 0 instead.
```

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

### Compare Two Key Events

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_keycmp.3.html

Use termkey_keycmp to compare two TermKeyKey structures. It returns a negative, zero, or positive value indicating if the first key is less than, equal to, or greater than the second key, respectively, after canonicalization.

```c
int termkey_keycmp(TermKey **_tk_, const TermKeyKey **_key1_, const TermKeyKey **_key2_);
```

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

### termkey_get_buffer_size

Source: http://www.leonerd.org.uk/code/libtermkey/doc/termkey_set_buffer_size.3.html

Retrieves the size of the buffer set by the last call to termkey_set_buffer_size, or the default initial size.

```APIDOC
## termkey_get_buffer_size

### Description
Returns the size of the buffer set by the last call to **termkey_set_buffer_size**(), or the default initial size of 256 bytes.

### Parameters
#### Path Parameters
- **_tk_** (TermKey ***) - Required - Pointer to the termkey instance.

### Return Value
Returns the current buffer size in bytes.
```