1TERMKEY(7) Miscellaneous Information Manual TERMKEY(7)
2
6 termkey - terminal keypress reading library
7
9 termkey is a library that allows programs to read and interpret key‐
10 press and other events from a terminal. It understands encoding schemes
11 used by terminals to encode keypresses, and UTF-8 , allowing it to re‐
12 turn events representing key events.
13 termkey operates in a pseudo object-oriented fashion. It provides one
15 function, termkey_new(3), that returns a pointer to a newly-allocated
16 structure. All other functions take this pointer as their first argu‐
17 ment. A typical use of this library would consist of a call to
18 termkey_new() to construct a new instance to represent the stdin
19 stream, then use the termkey_waitkey(3) function to wait for and inter‐
20 pret key press events. The termkey_destroy(3) function can be used to
21 deallocate resources used by the instance if the program has finished
22 using it.
23 Reading Events
25 Each instance of a termkey structure may be used in one of three ways
26 by the program. It may be used synchronously, blocking to wait for key‐
27 presses from a filehandle. It may be used asynchronously, returning
28 keypresses if they are available, while co-operating with a non-block‐
29 ing program. Or it may be used abstractly, interpreting key press bytes
30 fed to it directly by the containing program.
31 To obtain the next key event synchronously, a program may call
33 termkey_waitkey(3). This will either return an event from its internal
34 buffer, or block until a key is available, returning it when it is
35 ready. It behaves similarly to getc(3), fgetc(3), or similar, except
36 that it understands and returns entire key press events, rather than
37 single bytes.
38 To work with an asynchronous program, two other functions are used.
40 termkey_advisereadable(3) informs a termkey instance that more bytes of
41 input may be available from its file handle, so it should call read(2)
42 to obtain them. The program can then call termkey_getkey(3) to extract
43 key press events out of the internal buffer, in a way similar to
44 termkey_waitkey().
45 Finally, bytes of input can be fed into the termkey instance directly,
47 by calling termkey_push_bytes(3). This may be useful if the bytes have
48 already been read from the terminal by the application, or even in sit‐
49 uations that don't directly involve a terminal filehandle. Because of
50 these situations, it is possible to construct a termkey instance not
51 associated with a file handle, by passing -1 as the file descriptor.
52 A termkey instance contains a buffer of pending bytes that have been
54 read but not yet consumed by termkey_getkey(3). termkey_get_buffer_re‐
55 maining(3) returns the number of bytes of buffer space currently free
56 in the instance. termkey_set_buffer_size(3) and termkey_get_buf‐
57 fer_size(3) can be used to control and return the total size of this
58 buffer.
59 Key Events
61 Key events are stored in structures. Each structure holds details of
62 one key event. This structure is defined as follows.
63 typedef struct {
65 TermKeyType type;
66 union {
67 long codepoint; /* TERMKEY_TYPE_UNICODE */
68 int number; /* TERMKEY_TYPE_FUNCTION */
69 TermKeySym sym; /* TERMKEY_TYPE_KEYSYM */
70 } code;
71 int modifiers;
72 char utf8[7];
73 } TermKeyKey;
74 The type field indicates the type of event, and determines which of the
76 members of the code union is valid. It will be one of the following
77 constants:
78 TERMKEY_TYPE_UNICODE
80 a Unicode codepoint. This value indicates that code.codepoint is
81 valid, and will contain the codepoint number of the keypress. In
82 Unicode mode (if the TERMKEY_FLAG_UTF8 bit is set) this will be
83 its Unicode character number. In raw byte mode, this will con‐
84 tain a single 8-bit byte.
85 TERMKEY_TYPE_FUNCTION
87 a numbered function key. This value indicates that code.number
88 is valid, and contains the number of the numbered function key.
89 TERMKEY_TYPE_KEYSYM
91 a symbolic key. This value indicates that code.sym is valid, and
92 contains the symbolic key value.
93 TERMKEY_TYPE_MOUSE
95 a mouse button press, release, or movement. The code structure
96 should be considered opaque; termkey_interpret_mouse(3) may be
97 used to interpret it.
98 TERMKEY_TYPE_POSITION
100 a cursor position report. The code structure should be consid‐
101 ered opaque; termkey_interpret_position(3) may be used to inter‐
102 pret it.
103 TERMKEY_TYPE_MODEREPORT
105 an ANSI or DEC mode value report. The code structure should be
106 considered opaque; termkey_interpret_modereport(3) may be used
107 to interpret it.
108 TERMKEY_TYPE_DCS
110 a DCS sequence including its terminator. The code structure
111 should be considered opaque; termkey_interpret_string(3) may be
112 used to interpret it.
113 TERMKEY_TYPE_OSC
115 a OSC sequence including its terminator. The code structure
116 should be considered opaque; termkey_interpret_string(3) may be
117 used to interpret it.
118 TERMKEY_TYPE_UNKNOWN_CSI
120 an unrecognised CSI sequence. The code structure should be con‐
121 sidered opaque; termkey_interpret_csi(3) may be used to inter‐
122 pret it.
123 The modifiers bitmask is composed of a bitwise-or of the constants
125 TERMKEY_KEYMOD_SHIFT, TERMKEY_KEYMOD_CTRL and TERMKEY_KEYMOD_ALT.
126 The utf8 field is only set on events whose type is TERMKEY_TYPE_UNI‐
128 CODE. It should not be read for other events.
129 Key events that represent special keys (type is TERMKEY_TYPE_KEYSYM)
131 have with them as symbolic value that identifies the special key, in
132 code.sym. termkey_get_keyname(3) may be used to turn this symbolic
133 value into a string, and termkey_lookup_keyname(3) may be used to turn
134 string names into symbolic values.
135 A pair of functions are also provided to convert between key events and
137 strings. termkey_strfkey(3) converts a key event into a string, and
138 termkey_strpkey(3) parses a string turning it into a key event.
139 Key events may be compared for equality or ordering by using
141 termkey_keycmp(3).
142 Control Flags
144 Details of the behaviour of a termkey instance are controlled by two
145 bitmasks of flags. termkey_set_flags(3) and termkey_get_flags(3) set or
146 return the flags used to control the general behaviour, and
147 termkey_set_canonflags(3) and termkey_get_canonflags(3) set or return
148 the flags that control the key value canonicalisation behaviour per‐
149 formed by termkey_canonicalise(3).
150 The following control flags are recognised.
152 TERMKEY_FLAG_NOINTERPRET
154 Do not attempt to interpret C0 codes into keysyms. Instead re‐
155 port them as plain Ctrl-letter events.
156 TERMKEY_FLAG_CONVERTKP
158 Convert xterm's alternative keypad symbols into the plain ASCII
159 codes they would represent.
160 TERMKEY_FLAG_RAW
162 Ignore locale settings; do not attempt to recombine UTF-8 se‐
163 quences. Instead report only raw values.
164 TERMKEY_FLAG_UTF8
166 Ignore locale settings; force UTF-8 recombining on. This flag
167 overrides TERMKEY_FLAG_RAW.
168 TERMKEY_FLAG_NOTERMIOS
170 Even if the terminal file descriptor fd represents a TTY device,
171 do not call the tcsetattr(3) termios function on it to set it to
172 canonical input mode.
173 TERMKEY_FLAG_SPACESYMBOL
175 Report space as being a symbolic key rather than a Unicode code‐
176 point. Setting or clearing this flag in fact sets or clears the
177 TERMKEY_CANON_SPACESYMBOL canonicalisation flag.
178 TERMKEY_FLAG_CTRLC
180 Disable the SIGINT behaviour of Ctrl-C. If this flag is pro‐
181 vided, then Ctrl-C will be available as a normal keypress,
182 rather than sending the process group a SIGINT. This flag only
183 takes effect without TERMKEY_FLAG_NOTERMIOS; with it, none of
184 the signal keys are disabled anyway.
185 TERMKEY_FLAG_EINTR
187 Without this flag, IO operations are retried when interrupted by
188 a signal (EINTR). With this flag the TERMKEY_RES_ERROR result is
189 returned instead.
190 TERMKEY_FLAG_NOSTART
192 This flag is only meaningful to the constructor functions
193 termkey_new(3) and termkey_new_abstract(3). If set, the con‐
194 structor will not call termkey_start(3) as part of the construc‐
195 tion process. The user must call that at some future time before
196 the instance will be usable.
197 The following canonicalisation flags are recognised.
199 TERMKEY_CANON_SPACESYMBOL
201 If this flag is set then a Unicode space character is repre‐
202 sented using the TERMKEY_SYM_SPACE symbol. If this flag is not
203 set, it is represented by the U+0020 Unicode codepoint.
204 TERMKEY_CANON_DELBS
206 If this flag is set then an ASCII DEL character is represented
207 by the TERMKEY_SYM_BACKSPACE symbol. If not, it is represented
208 by TERMKEY_SYM_DEL. An ASCII BS character is always represented
209 by TERMKEY_SYM_BACKSPACE, regardless of this flag.
210 Multi-byte Events
212 Special keys, mouse events, and UTF-8 encoded Unicode text, are all
213 represented by more than one byte. If the start of a multi-byte se‐
214 quence is seen by termkey_waitkey() it will wait a short time to see if
215 the remainder of the sequence arrives. If the sequence remains unfin‐
216 ished after this timeout, it will be returned in its incomplete state.
217 Partial escape sequences are returned as an Escape key (TERMKEY_SYM_ES‐
218 CAPE) followed by the text contained in the sequence. Partial UTF-8 se‐
219 quences are returned as the Unicode replacement character, U+FFFD.
220 The amount of time that the termkey instance will wait is set by
222 termkey_set_waittime(3), and is returned by termkey_get_waittime(3).
223 Initially it will be set to 50 miliseconds.
224 Mouse Events
226 The TERMKEY_TYPE_MOUSE event type indicates a mouse event. The code
227 field of the event structure should be considered opaque, though modi‐
228 fiers will be valid. In order to obtain the details of the mouse event,
229 call termkey_interpret_mouse(3) passing the event structure and point‐
230 ers to integers to store the result in.
231 termkey recognises three mouse protocols: the original X10 protocol
233 (CSI M followed by three bytes), SGR encoding (CSI < ... M, as re‐
234 quested by CSI ? 1006 h), and rxvt encoding (CSI ... M, as requested by
235 CSI ? 1015 h). Which encoding is in use is inferred automatically by
236 termkey, and does not need to be specified explicitly.
237 Position Events
239 The TERMKEY_TYPE_POSITION event type indicates a cursor position re‐
240 port. This is typically sent by a terminal in response to the Report
241 Cursor Position command (CSI ? 6 n). The event bytes are opaque, but
242 can be obtained by calling termkey_interpret_position(3) passing the
243 event structure and pointers to integers to store the result in. Note
244 that only a DEC CPR sequence (CSI ? R) is recognised, and not the non-
245 DEC prefixed CSI R because the latter could be interpreted as the F3
246 function key instead.
247 Mode Reports
249 The TERMKEY_TYPE_MODEREPORT event type indicates an ANSI or DEC mode
250 report. This is typically sent by a terminal in response to the Request
251 Mode command (CSI $p or CSI ? $p). The event bytes are opaque, but can
252 be obtained by calling termkey_interpret_modereport(3) passing the
253 event structure and pointers to integers to store the result in.
254 Control Strings
256 The TERMKEY_TYPE_DCS and TERMKEY_TYPE_OSC event types indicate a DCS or
257 OSC control string. These are typically sent by the terminal in re‐
258 sponse of similar kinds of strings being sent as queries by the appli‐
259 cation. The event bytes are opaque, but the body of the string itself
260 can be obtained by calling termkey_interpret_string(3) immediately af‐
261 ter this event is received. The underlying termkey instance itself can
262 only store one pending string, so the application should be sure to
263 call this function in a timely manner soon after the event is received;
264 at the very least, before calling any other functions that will insert
265 bytes into or remove key events from the instance.
266 Unrecognised CSIs
268 The TERMKEY_TYPE_UNKNOWN_CSI event type indicates a CSI sequence that
269 the termkey does not recognise. It will have been extracted from the
270 stream, but is available to the application to inspect by calling
271 termkey_interpret_csi(3). It is important that if the application
272 wishes to inspect this sequence it is done immediately, before any
273 other IO operations on the termkey instance (specifically, before call‐
274 ing termkey_waitkey() or termkey_getkey() again), otherwise the buffer
275 space consumed by the sequence will be overwritten. Other types of key
276 event do not suffer this limitation as the TermKeyKey structure is suf‐
277 ficient to contain all the information required.
278
280 termkey_new(3), termkey_waitkey(3), termkey_getkey(3)
281 TERMKEY(7)