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 resources 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() returns. 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_remaining(3), termkey_get_buffer_size(3), termkey(7)

                                                                                   TERMKEY_NEW(3)