DragonFly On-Line Manual Pages

TERMKEY_GETKEY(3)     DragonFly Library Functions Manual     TERMKEY_GETKEY(3)

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)