1TERMKEY_GETKEY(3) Library Functions Manual TERMKEY_GETKEY(3)
2
6 termkey_getkey, termkey_getkey_force - retrieve the next key event
7
9 #include <termkey.h>
10 TermKeyResult termkey_getkey(TermKey *tk, TermKeyKey *key);
12 TermKeyResult termkey_getkey_force(TermKey *tk, TermKeyKey *key);
13 Link with -ltermkey.
15
17 termkey_getkey() attempts to retrieve a single keypress event from the
18 termkey(7) instance buffer, and put it in the structure referred to by
19 key. It returns one of the following values:
20 TERMKEY_RES_KEY
22 a complete keypress was removed from the buffer, and has been
23 placed in the key structure.
24 TERMKEY_RES_AGAIN
26 a partial keypress event was found in the buffer, but it does
27 not yet contain all the bytes required. An indication of what
28 termkey_getkey_force() would return has been placed in the key
29 structure.
30 TERMKEY_RES_NONE
32 no bytes are waiting in the buffer.
33 TERMKEY_RES_EOF
35 no bytes are ready and the input stream is now closed.
36 TERMKEY_RES_ERROR
38 called with terminal IO stopped, due to termkey_stop(3). In this
39 case errno will be set to EINVAL.
40 termkey_getkey_force() is similar to termkey_getkey() but will not
42 return TERMKEY_RES_AGAIN if a partial match is found. Instead, it will
43 force an interpretation of the bytes, even if this means interpreting
44 the start of an Escape-prefixed multi-byte sequence as a literal Escape
45 key followed by normal letters.
46 Neither of these functions will block or perform any IO operations on
48 the underlying filehandle. To use the instance in an asynchronous pro‐
49 gram, see termkey_advisereadable(3). For a blocking call suitable for
50 use in a synchronous program, use termkey_waitkey(3) instead of
51 termkey_getkey(). For providing input without a readable filehandle,
52 use termkey_push_bytes(3).
53 Before returning, this function canonicalises the key structure accord‐
55 ing to the rules given for termkey_canonicalise(3).
56
58 termkey_getkey() returns an enumeration of one of TERMKEY_RES_KEY, TEM‐
59 RKEY_RES_AGAIN, TERMKEY_RES_NONE, TERMKEY_RES_EOF or TERMKEY_RES_ERROR.
60 termkey_getkey_force() returns one of the above, except for
61 TERMKEY_RES_AGAIN.
62
64 The following example program prints details of every keypress until
65 the user presses Ctrl-C. It demonstrates how to use the termkey
66 instance in a typical poll(2)-driven asynchronous program, which may
67 include mixed IO with other file handles.
68 // <poll.h> might need this for sigset_t
70 #define _XOPEN_SOURCE 600
71 #include <poll.h>
73 #include <stdio.h>
74 #include "termkey.h"
76 static void on_key(TermKey *tk, TermKeyKey *key)
78 {
79 char buffer[50];
80 termkey_strfkey(tk, buffer, sizeof buffer, key, TERMKEY_FORMAT_VIM);
81 printf("%s\n", buffer);
82 }
83 int main(int argc, char *argv[])
85 {
86 TERMKEY_CHECK_VERSION;
87 TermKey *tk = termkey_new(0, 0);
89 if(!tk) {
91 fprintf(stderr, "Cannot allocate termkey instance\n");
92 exit(1);
93 }
94 struct pollfd fd;
96 fd.fd = 0; /* the file descriptor we passed to termkey_new() */
98 fd.events = POLLIN;
99 TermKeyResult ret;
101 TermKeyKey key;
102 int running = 1;
104 int nextwait = -1;
105 while(running) {
107 if(poll(&fd, 1, nextwait) == 0) {
108 // Timed out
109 if(termkey_getkey_force(tk, &key) == TERMKEY_RES_KEY)
110 on_key(tk, &key);
111 }
112 if(fd.revents & (POLLIN|POLLHUP|POLLERR))
114 termkey_advisereadable(tk);
115 while((ret = termkey_getkey(tk, &key)) == TERMKEY_RES_KEY) {
117 on_key(tk, &key);
118 if(key.type == TERMKEY_TYPE_UNICODE &&
120 key.modifiers & TERMKEY_KEYMOD_CTRL &&
121 (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
122 running = 0;
123 }
124 if(ret == TERMKEY_RES_AGAIN)
126 nextwait = termkey_get_waittime(tk);
127 else
128 nextwait = -1;
129 }
130 termkey_destroy(tk);
132 }
133
135 termkey_advisereadable(3), termkey_waitkey(3), termkey_get_waittime(3),
136 termkey(7)
137 TERMKEY_GETKEY(3)