TERMKEY\_WAITKEY(3) Library Functions Manual TERMKEY\_WAITKEY(3)

# [NAME](#NAME)

termkey\_waitkey - wait for and retrieve the next key event

# [SYNOPSIS](#SYNOPSIS)

```
#include <termkey.h>

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

Link with *-ltermkey*.

# [DESCRIPTION](#DESCRIPTION)

**termkey\_waitkey**() attempts to retrieve a single keypress event from the [**termkey**(7)](/man/os/libtermkey/termkey.7) instance buffer, and put it in the structure referred to by *key*. If successful it will return **TERMKEY\_RES\_KEY** to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return **TERMKEY\_RES\_EOF**. If no filehandle is associated with this instance, **TERMKEY\_RES\_ERROR** is returned with *errno* set to **EBADF**.

Before returning, this function canonicalises the *key* structure according to the rules given for [**termkey\_canonicalise**(3)](/man/os/libtermkey/termkey_canonicalise.3).

Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using **termkey**, **termkey\_waitkey**() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by [**termkey\_set\_waittime**(3)](/man/os/libtermkey/termkey_set_waittime.3).

# [RETURN VALUE](#RETURN_VALUE)

**termkey\_waitkey**() returns one of the following constants:

[**TERMKEY\_RES\_KEY**](#TERMKEY_RES_KEY)

A key event as been provided.

[**TERMKEY\_RES\_EOF**](#TERMKEY_RES_EOF)

No key events are ready and the terminal has been closed, so no more will arrive.

[**TERMKEY\_RES\_ERROR**](#TERMKEY_RES_ERROR)

An IO error occurred. *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. If this is called with terminal IO stopped, due to [**termkey\_stop**(3)](/man/os/libtermkey/termkey_stop.3) then *errno* will be set to **EINVAL**.

# [EXAMPLE](#EXAMPLE)

The following example program prints details of every keypress until the user presses *Ctrl-C*.

```
// we want optarg
#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);


  }


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


  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("Key %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);
}


```

# [COMPATIBILITY](#COMPATIBILITY)

This function is not available on Windows.

# [SEE ALSO](#SEE_ALSO)

[**termkey\_getkey**(3)](/man/os/libtermkey/termkey_getkey.3), [**termkey\_set\_waittime**(3)](/man/os/libtermkey/termkey_set_waittime.3), [**termkey**(7)](/man/os/libtermkey/termkey.7)

---

Document: termkey_waitkey(3) from libtermkey 0.22-r8 (Chainguard OS)