FreeBSD Manual Pages
TERMKEY_GETKEY(3) 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 re- turn 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 pro- gram, 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 accord- ing to the rules given for termkey_canonicalise(3). RETURN VALUE termkey_getkey() returns an enumeration of one of TERMKEY_RES_KEY, TEM- RKEY_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 in- stance in a typical poll(2)-driven asynchronous program, which may in- clude 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)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=termkey_getkey&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>