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)

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

home | help