1TERMKEY(7)             Miscellaneous Information Manual             TERMKEY(7)
2
3
4

NAME

6       termkey - terminal keypress reading library
7

DESCRIPTION

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
12       return events representing key events.
13
14       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
24   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
32       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
39       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
46       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
53       A termkey instance contains a buffer of pending bytes  that  have  been
54       read  but  not  yet  consumed  by  termkey_getkey(3).  termkey_get_buf‐
55       fer_remaining(3) returns the number of bytes of buffer space  currently
56       free  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
60   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
64           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
75       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
79       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
86       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
90       TERMKEY_TYPE_KEYSYM
91              a symbolic key. This value indicates that code.sym is valid, and
92              contains the symbolic key value.
93
94       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
99       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
104       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
109       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
114       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
119       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
124       The modifiers bitmask is composed of  a  bitwise-or  of  the  constants
125       TERMKEY_KEYMOD_SHIFT, TERMKEY_KEYMOD_CTRL and TERMKEY_KEYMOD_ALT.
126
127       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
130       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
136       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
140       Key  events  may  be  compared  for  equallity  or  ordering  by  using
141       termkey_keycmp(3).
142
143   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
151       The following control flags are recognised.
152
153       TERMKEY_FLAG_NOINTERPRET
154              Do not attempt to  interpret  C0  codes  into  keysyms.  Instead
155              report them as plain Ctrl-letter events.
156
157       TERMKEY_FLAG_CONVERTKP
158              Convert  xterm's alternative keypad symbols into the plain ASCII
159              codes they would represent.
160
161       TERMKEY_FLAG_RAW
162              Ignore locale  settings;  do  not  attempt  to  recombine  UTF-8
163              sequences. Instead report only raw values.
164
165       TERMKEY_FLAG_UTF8
166              Ignore  locale  settings;  force UTF-8 recombining on. This flag
167              overrides TERMKEY_FLAG_RAW.
168
169       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
174       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
179       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
186       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
191       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
198       The following canonicalisation flags are recognised.
199
200       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
205       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
211   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
214       sequence  is seen by termkey_waitkey() it will wait a short time to see
215       if the remainder of the  sequence  arrives.  If  the  sequence  remains
216       unfinished  after  this  timeout, it will be returned in its incomplete
217       state.  Partial  escape  sequences  are  returned  as  an  Escape   key
218       (TERMKEY_SYM_ESCAPE)  followed  by  the text contained in the sequence.
219       Partial UTF-8 sequences are returned as the Unicode replacement charac‐
220       ter, U+FFFD.
221
222       The  amount  of  time  that  the  termkey  instance will wait is set by
223       termkey_set_waittime(3), and is  returned  by  termkey_get_waittime(3).
224       Initially it will be set to 50 miliseconds.
225
226   Mouse Events
227       The  TERMKEY_TYPE_MOUSE  event  type  indicates a mouse event. The code
228       field of the event structure should be considered opaque, though  modi‐
229       fiers will be valid. In order to obtain the details of the mouse event,
230       call termkey_interpret_mouse(3) passing the event structure and  point‐
231       ers to integers to store the result in.
232
233       termkey  recognises  three  mouse  protocols: the original X10 protocol
234       (CSI M followed by  three  bytes),  SGR  encoding  (CSI  <  ...  M,  as
235       requested  by CSI ? 1006 h), and rxvt encoding (CSI ... M, as requested
236       by CSI ? 1015 h). Which encoding is in use is inferred automatically by
237       termkey, and does not need to be specified explicitly.
238
239   Position Events
240       The  TERMKEY_TYPE_POSITION  event  type  indicates  a  cursor  position
241       report. This is typically sent by a terminal in response to the  Report
242       Cursor  Position  command  (CSI ? 6 n). The event bytes are opaque, but
243       can be obtained by calling  termkey_interpret_position(3)  passing  the
244       event  structure  and pointers to integers to store the result in. Note
245       that only a DEC CPR sequence (CSI ? R) is recognised, and not the  non-
246       DEC  prefixed  CSI  R because the latter could be interpreted as the F3
247       function key instead.
248
249   Mode Reports
250       The TERMKEY_TYPE_MODEREPORT event type indicates an ANSI  or  DEC  mode
251       report. This is typically sent by a terminal in response to the Request
252       Mode command (CSI $p or CSI ? $p). The event bytes are opaque, but  can
253       be  obtained  by  calling  termkey_interpret_modereport(3)  passing the
254       event structure and pointers to integers to store the result in.
255
256   Control Strings
257       The TERMKEY_TYPE_DCS and TERMKEY_TYPE_OSC event types indicate a DCS or
258       OSC  control  string.  These  are  typically  sent  by  the terminal in
259       response of similar kinds of strings  being  sent  as  queries  by  the
260       application.  The  event  bytes  are opaque, but the body of the string
261       itself can be obtained by calling  termkey_interpret_string(3)  immedi‐
262       ately  after  this  event  is received. The underlying termkey instance
263       itself can only store one pending string, so the application should  be
264       sure  to  call this function in a timely manner soon after the event is
265       received; at the very least, before calling any  other  functions  that
266       will insert bytes into or remove key events from the instance.
267
268   Unrecognised CSIs
269       The  TERMKEY_TYPE_UNKNOWN_CSI  event type indicates a CSI sequence that
270       the termkey does not recognise. It will have been  extracted  from  the
271       stream,  but  is  available  to  the  application to inspect by calling
272       termkey_interpret_csi(3). It  is  important  that  if  the  application
273       wishes  to  inspect  this  sequence  it is done immediately, before any
274       other IO operations on the termkey instance (specifically, before call‐
275       ing  termkey_waitkey() or termkey_getkey() again), otherwise the buffer
276       space consumed by the sequence will be overwritten. Other types of  key
277       event do not suffer this limitation as the TermKeyKey structure is suf‐
278       ficient to contain all the information required.
279

SEE ALSO

281       termkey_new(3), termkey_waitkey(3), termkey_getkey(3)
282
283
284
285                                                                    TERMKEY(7)
Impressum