TERMKEY_WAITKEY(3) Library Functions Manual TERMKEY_WAITKEY(3) NAME termkey_waitkey - wait for and retrieve the next key event SYNOPSIS #include <termkey.h> TermKeyResult termkey_waitkey(TermKey *tk, TermKeyKey *key); Link with -ltermkey. DESCRIPTION termkey_waitkey() attempts to retrieve a single keypress event from the 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). Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application us- ing 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 se- quence 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). RETURN VALUE termkey_waitkey() returns one of the following constants: TERMKEY_RES_KEY A key event as been provided. TERMKEY_RES_EOF No key events are ready and the terminal has been closed, so no more will arrive. 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) then er- rno will be set to EINVAL. 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 This function is not available on Windows. SEE ALSO termkey_getkey(3), termkey_set_waittime(3), termkey(7) TERMKEY_WAITKEY(3)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | COMPATIBILITY | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=termkey_waitkey&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>