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)