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

FreeBSD Manual Pages

  
 
  

home | help
TERMKEY_NEW(3)		   Library Functions Manual		TERMKEY_NEW(3)

NAME
       termkey_new, termkey_destroy - create or	destroy	new termkey instance

SYNOPSIS
       #include	<termkey.h>

       TERMKEY_CHECK_VERSION;
       TermKey *termkey_new(int	fd, int	flags);
       TermKey *termkey_new_abstract(const char	*term, int flags);
       void termkey_destroy(TermKey *tk);

       Link with -ltermkey.

DESCRIPTION
       termkey_new()  creates  a new termkey(7)	instance connected to the file
       handle opened by	fd using the flags. The	TermKey	 structure  should  be
       considered opaque; its contents are not intended	for use	outside	of the
       library.

       termkey_new_abstract() creates a	new termkey() instance	with  no  file
       handle  associated.  As this is usually done for	handling other sources
       of terminal byte	input, it also takes a string indicating the  termtype
       to use.

       termkey_destroy()  destroys  the	 given	instance  and releases any re-
       sources controlled by it. It will not close the	underlying  filehandle
       given as	the fd argument	to termkey_new().

       The constructor attempts	to detect if the current locale	is UTF-8 aware
       or not, and sets	either the TERMKEY_FLAG_UTF8 or	TERMKEY_FLAG_RAW flag.
       One  of	these  two bits	will always be in effect. The current flags in
       effect can be obtained by termkey_get_flags(3).

       If a file handle	is provided, the terminfo driver may send a string  to
       initialise  or  set  the	state of the terminal before termkey_new() re-
       turns. This will	not be done if no file handle is provided, or  if  the
       file  handle  is	 a  pipe  (S_ISFIFO()).	 In  this  case	it will	be the
       caller's	responsibility to ensure the terminal is in the	correct	 mode.
       Once  initialised,  the terminal	can be stopped by termkey_stop(3), and
       started again by	termkey_start(3).

       This behaviour is modified by the TERMKEY_FLAG_NOSTART flag. If	passed
       in  the flags argument then the instance	will not be started yet	by the
       constructor; the	caller must  invoke  termkey_start()  at  some	future
       point before the	instance will be usable.

VERSION	CHECK MACRO
       Before  calling	any  functions	in the termkey library,	an application
       should use the TERMKEY_CHECK_VERSION macro to  check  that  the	loaded
       version	of  the	library	is compatible with the version it was compiled
       against.	This should be done early on, ideally just after entering  its
       main() function.

RETURN VALUE
       If  successful, termkey_new() returns a pointer to the new instance. On
       failure,	NULL is	returned with  errno  set  to  indicate	 the  failure.
       termkey_destroy() returns no value.

ERRORS
       ENOENT No driver	was able to recognise the given	terminal type.

       ENOMEM A	call to	malloc(3) failed to allocate memory.

       Additionally,  termkey_new()  may fail if fstat(2) or write(2) fails on
       the given file handle.

SEE ALSO
       termkey_waitkey(3),    termkey_advisereadable(3),    termkey_getkey(3),
       termkey_get_flags(3),   termkey_get_fd(3),   termkey_get_buffer_remain-
       ing(3), termkey_get_buffer_size(3), termkey(7)

								TERMKEY_NEW(3)

NAME | SYNOPSIS | DESCRIPTION | VERSION CHECK MACRO | RETURN VALUE | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=termkey_new&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help