NAME

       termkey_getkey, termkey_getkey_force - retrieve the next key event

SYNOPSIS

       #include <termkey.h>

       TermKeyResult termkey_getkey(TermKey *tk, TermKeyKey *key);
       TermKeyResult termkey_getkey_force(TermKey *tk, TermKeyKey *key);

       Link with -ltermkey.

DESCRIPTION

       termkey_getkey()  attempts  to  retrieve a single keypress event from the termkey(7) instance buffer, and
       put it in the structure referred to by key. It returns one of the following values:

       TERMKEY_RES_KEY
              a complete keypress was removed from the buffer, and has been placed in the key structure.

       TERMKEY_RES_AGAIN
              a partial keypress event was found in the buffer, but it  does  not  yet  contain  all  the  bytes
              required.  An  indication  of  what termkey_getkey_force() would return has been placed in the key
              structure.

       TERMKEY_RES_NONE
              no bytes are waiting in the buffer.

       TERMKEY_RES_EOF
               no bytes are ready and the input stream is now closed.

       TERMKEY_RES_ERROR
              called with terminal IO stopped, due to termkey_stop(3). In this case errno will be set to EINVAL.

       termkey_getkey_force() is similar to termkey_getkey() but will not return TERMKEY_RES_AGAIN if a  partial
       match  is  found.  Instead, it will force an interpretation of the bytes, even if this means interpreting
       the start of an Escape-prefixed multi-byte sequence as a literal Escape key followed by normal letters.

       Neither of these functions will block or perform any IO operations on the underlying filehandle.  To  use
       the  instance in an asynchronous program, see termkey_advisereadable(3). For a blocking call suitable for
       use in a synchronous program, use termkey_waitkey(3) instead of  termkey_getkey().  For  providing  input
       without a readable filehandle, use termkey_push_bytes(3).

       Before  returning,  this  function  canonicalises  the  key  structure  according  to the rules given for
       termkey_canonicalise(3).

RETURN VALUE

       termkey_getkey() returns an enumeration of one of TERMKEY_RES_KEY,  TEMRKEY_RES_AGAIN,  TERMKEY_RES_NONE,
       TERMKEY_RES_EOF  or  TERMKEY_RES_ERROR.  termkey_getkey_force()  returns  one  of  the  above, except for
       TERMKEY_RES_AGAIN.

EXAMPLE

       The following example program prints details  of  every  keypress  until  the  user  presses  Ctrl-C.  It
       demonstrates  how to use the termkey instance in a typical poll(2)-driven asynchronous program, which may
       include mixed IO with other file handles.

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

SEE ALSO

       termkey_advisereadable(3), termkey_waitkey(3), termkey_get_waittime(3), termkey(7)

                                                                                               TERMKEY_GETKEY(3)