Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TERMKEY(7)	       Miscellaneous Information Manual		    TERMKEY(7)

       termkey - terminal keypress reading library

       termkey	is  a  library that allows programs to read and	interpret key-
       press and other events from a terminal. It understands encoding schemes
       used  by	terminals to encode keypresses,	and UTF-8 , allowing it	to re-
       turn events representing	key events.

       termkey operates	in a pseudo object-oriented fashion. It	 provides  one
       function,  termkey_new(3),  that	returns	a pointer to a newly-allocated
       structure. All other functions take this	pointer	as their  first	 argu-
       ment.  A	 typical  use  of  this	 library  would	 consist  of a call to
       termkey_new() to	construct  a  new  instance  to	 represent  the	 stdin
       stream, then use	the termkey_waitkey(3) function	to wait	for and	inter-
       pret key	press events. The termkey_destroy(3) function can be  used  to
       deallocate  resources  used by the instance if the program has finished
       using it.

   Reading Events
       Each instance of	a termkey structure may	be used	in one of  three  ways
       by the program. It may be used synchronously, blocking to wait for key-
       presses from a filehandle. It may  be  used  asynchronously,  returning
       keypresses  if they are available, while	co-operating with a non-block-
       ing program. Or it may be used abstractly, interpreting key press bytes
       fed to it directly by the containing program.

       To  obtain  the	next  key  event  synchronously,  a  program  may call
       termkey_waitkey(3). This	will either return an event from its  internal
       buffer,	or  block  until  a  key is available, returning it when it is
       ready. It behaves similarly to getc(3), fgetc(3),  or  similar,	except
       that  it	 understands  and returns entire key press events, rather than
       single bytes.

       To work with an asynchronous program, two  other	 functions  are	 used.
       termkey_advisereadable(3) informs a termkey instance that more bytes of
       input may be available from its file handle, so it should call  read(2)
       to  obtain them.	The program can	then call termkey_getkey(3) to extract
       key press events	out of the  internal  buffer,  in  a  way  similar  to

       Finally,	 bytes of input	can be fed into	the termkey instance directly,
       by calling termkey_push_bytes(3). This may be useful if the bytes  have
       already been read from the terminal by the application, or even in sit-
       uations that don't directly involve a terminal filehandle.  Because  of
       these  situations,  it  is possible to construct	a termkey instance not
       associated with a file handle, by passing -1 as the file	descriptor.

       A termkey instance contains a buffer of pending bytes  that  have  been
       read  but not yet consumed by termkey_getkey(3).	termkey_get_buffer_re-
       maining(3) returns the number of	bytes of buffer	space  currently  free
       in   the	  instance.  termkey_set_buffer_size(3)	 and  termkey_get_buf-
       fer_size(3) can be used to control and return the total	size  of  this

   Key Events
       Key  events  are	 stored	in structures. Each structure holds details of
       one key event. This structure is	defined	as follows.

	   typedef struct {
	       TermKeyType type;
	       union {
		   long	      codepoint; /* TERMKEY_TYPE_UNICODE  */
		   int	      number;	 /* TERMKEY_TYPE_FUNCTION */
		   TermKeySym sym;	 /* TERMKEY_TYPE_KEYSYM	  */
	       } code;
	       int modifiers;
	       char utf8[7];
	   } TermKeyKey;

       The type	field indicates	the type of event, and determines which	of the
       members	of  the	 code  union is	valid. It will be one of the following

	      a	Unicode	codepoint. This	value indicates	that code.codepoint is
	      valid, and will contain the codepoint number of the keypress. In
	      Unicode mode (if the TERMKEY_FLAG_UTF8 bit is set) this will  be
	      its  Unicode  character number. In raw byte mode,	this will con-
	      tain a single 8-bit byte.

	      a	numbered function key. This value indicates  that  code.number
	      is valid,	and contains the number	of the numbered	function key.

	      a	symbolic key. This value indicates that	code.sym is valid, and
	      contains the symbolic key	value.

	      a	mouse button press, release, or	movement. The  code  structure
	      should  be  considered opaque; termkey_interpret_mouse(3)	may be
	      used to interpret	it.

	      a	cursor position	report.	The code structure should  be  consid-
	      ered opaque; termkey_interpret_position(3) may be	used to	inter-
	      pret it.

	      an ANSI or DEC mode value	report.	The code structure  should  be
	      considered  opaque;  termkey_interpret_modereport(3) may be used
	      to interpret it.

	      a	DCS sequence including	its  terminator.  The  code  structure
	      should  be considered opaque; termkey_interpret_string(3)	may be
	      used to interpret	it.

	      a	OSC sequence including	its  terminator.  The  code  structure
	      should  be considered opaque; termkey_interpret_string(3)	may be
	      used to interpret	it.

	      an unrecognised CSI sequence. The	code structure should be  con-
	      sidered  opaque;	termkey_interpret_csi(3) may be	used to	inter-
	      pret it.

       The modifiers bitmask is	composed of  a	bitwise-or  of	the  constants

       The  utf8  field	 is only set on	events whose type is TERMKEY_TYPE_UNI-
       CODE. It	should not be read for other events.

       Key events that represent special keys  (type  is  TERMKEY_TYPE_KEYSYM)
       have  with  them	 as symbolic value that	identifies the special key, in
       code.sym. termkey_get_keyname(3)	may be	used  to  turn	this  symbolic
       value  into a string, and termkey_lookup_keyname(3) may be used to turn
       string names into symbolic values.

       A pair of functions are also provided to	convert	between	key events and
       strings.	 termkey_strfkey(3)  converts  a  key event into a string, and
       termkey_strpkey(3) parses a string turning it into a key	event.

       Key  events  may	 be  compared  for  equality  or  ordering  by	 using

   Control Flags
       Details	of  the	 behaviour of a	termkey	instance are controlled	by two
       bitmasks	of flags. termkey_set_flags(3) and termkey_get_flags(3)	set or
       return	the   flags   used  to	control	 the  general  behaviour,  and
       termkey_set_canonflags(3) and termkey_get_canonflags(3) set  or	return
       the  flags  that	 control the key value canonicalisation	behaviour per-
       formed by termkey_canonicalise(3).

       The following control flags are recognised.

	      Do not attempt to	interpret C0 codes into	keysyms.  Instead  re-
	      port them	as plain Ctrl-letter events.

	      Convert  xterm's alternative keypad symbols into the plain ASCII
	      codes they would represent.

	      Ignore locale settings; do not attempt to	 recombine  UTF-8  se-
	      quences. Instead report only raw values.

	      Ignore  locale  settings;	 force UTF-8 recombining on. This flag
	      overrides	TERMKEY_FLAG_RAW.

	      Even if the terminal file	descriptor fd represents a TTY device,
	      do not call the tcsetattr(3) termios function on it to set it to
	      canonical	input mode.

	      Report space as being a symbolic key rather than a Unicode code-
	      point.  Setting or clearing this flag in fact sets or clears the
	      TERMKEY_CANON_SPACESYMBOL	canonicalisation flag.

	      Disable the SIGINT behaviour of Ctrl-C. If  this	flag  is  pro-
	      vided,  then  Ctrl-C  will  be  available	 as a normal keypress,
	      rather than sending the process group a SIGINT. This  flag  only
	      takes  effect  without  TERMKEY_FLAG_NOTERMIOS; with it, none of
	      the signal keys are disabled anyway.

	      Without this flag, IO operations are retried when	interrupted by
	      a	signal (EINTR).	With this flag the TERMKEY_RES_ERROR result is
	      returned instead.

	      This flag	 is  only  meaningful  to  the	constructor  functions
	      termkey_new(3)  and  termkey_new_abstract(3).  If	 set, the con-
	      structor will not	call termkey_start(3) as part of the construc-
	      tion process. The	user must call that at some future time	before
	      the instance will	be usable.

       The following canonicalisation flags are	recognised.

	      If this flag is set then a Unicode  space	 character  is	repre-
	      sented  using  the TERMKEY_SYM_SPACE symbol. If this flag	is not
	      set, it is represented by	the U+0020 Unicode codepoint.

	      If this flag is set then an ASCII	DEL character  is  represented
	      by  the  TERMKEY_SYM_BACKSPACE symbol. If	not, it	is represented
	      by TERMKEY_SYM_DEL. An ASCII BS character	is always  represented
	      by TERMKEY_SYM_BACKSPACE,	regardless of this flag.

   Multi-byte Events
       Special	keys,  mouse  events,  and UTF-8 encoded Unicode text, are all
       represented by more than	one byte. If the start	of  a  multi-byte  se-
       quence is seen by termkey_waitkey() it will wait	a short	time to	see if
       the remainder of	the sequence arrives. If the sequence  remains	unfin-
       ished  after this timeout, it will be returned in its incomplete	state.
       Partial escape sequences	are returned as	an Escape key (TERMKEY_SYM_ES-
       CAPE) followed by the text contained in the sequence. Partial UTF-8 se-
       quences are returned as the Unicode replacement character, U+FFFD.

       The amount of time that the  termkey  instance  will  wait  is  set  by
       termkey_set_waittime(3),	 and  is  returned by termkey_get_waittime(3).
       Initially it will be set	to 50 miliseconds.

   Mouse Events
       The TERMKEY_TYPE_MOUSE event type indicates a  mouse  event.  The  code
       field  of the event structure should be considered opaque, though modi-
       fiers will be valid. In order to	obtain the details of the mouse	event,
       call  termkey_interpret_mouse(3)	passing	the event structure and	point-
       ers to integers to store	the result in.

       termkey recognises three	mouse protocols:  the  original	 X10  protocol
       (CSI  M	followed  by  three  bytes), SGR encoding (CSI < ... M,	as re-
       quested by CSI ?	1006 h), and rxvt encoding (CSI	... M, as requested by
       CSI  ?  1015  h). Which encoding	is in use is inferred automatically by
       termkey,	and does not need to be	specified explicitly.

   Position Events
       The TERMKEY_TYPE_POSITION event type indicates a	 cursor	 position  re-
       port.  This  is	typically sent by a terminal in	response to the	Report
       Cursor Position command (CSI ? 6	n). The	event bytes  are  opaque,  but
       can  be	obtained  by calling termkey_interpret_position(3) passing the
       event structure and pointers to integers	to store the result  in.  Note
       that  only a DEC	CPR sequence (CSI ? R) is recognised, and not the non-
       DEC prefixed CSI	R because the latter could be interpreted  as  the  F3
       function	key instead.

   Mode	Reports
       The  TERMKEY_TYPE_MODEREPORT  event  type indicates an ANSI or DEC mode
       report. This is typically sent by a terminal in response	to the Request
       Mode  command (CSI $p or	CSI ? $p). The event bytes are opaque, but can
       be obtained  by	calling	 termkey_interpret_modereport(3)  passing  the
       event structure and pointers to integers	to store the result in.

   Control Strings
       The TERMKEY_TYPE_DCS and	TERMKEY_TYPE_OSC event types indicate a	DCS or
       OSC control string. These are typically sent by	the  terminal  in  re-
       sponse  of similar kinds	of strings being sent as queries by the	appli-
       cation. The event bytes are opaque, but the body	of the	string	itself
       can  be obtained	by calling termkey_interpret_string(3) immediately af-
       ter this	event is received. The underlying termkey instance itself  can
       only  store  one	 pending  string, so the application should be sure to
       call this function in a timely manner soon after	the event is received;
       at  the very least, before calling any other functions that will	insert
       bytes into or remove key	events from the	instance.

   Unrecognised	CSIs
       The TERMKEY_TYPE_UNKNOWN_CSI event type indicates a CSI	sequence  that
       the  termkey  does  not recognise. It will have been extracted from the
       stream, but is available	to  the	 application  to  inspect  by  calling
       termkey_interpret_csi(3).  It  is  important  that  if  the application
       wishes to inspect this sequence it  is  done  immediately,  before  any
       other IO	operations on the termkey instance (specifically, before call-
       ing termkey_waitkey() or	termkey_getkey() again), otherwise the	buffer
       space  consumed by the sequence will be overwritten. Other types	of key
       event do	not suffer this	limitation as the TermKeyKey structure is suf-
       ficient to contain all the information required.

       termkey_new(3), termkey_waitkey(3), termkey_getkey(3)



Want to link to this manual page? Use this URL:

home | help