1TERMKEY_NEW(3) Library Functions Manual TERMKEY_NEW(3)
2
6 termkey_new, termkey_destroy - create or destroy new termkey instance
7
9 #include <termkey.h>
10 TERMKEY_CHECK_VERSION;
12 TermKey *termkey_new(int fd, int flags);
13 TermKey *termkey_new_abstract(const char *term, int flags);
14 void termkey_destroy(TermKey *tk);
15 Link with -ltermkey.
17
19 termkey_new() creates a new termkey(7) instance connected to the file
20 handle opened by fd using the flags. The TermKey structure should be
21 considered opaque; its contents are not intended for use outside of the
22 library.
23 termkey_new_abstract() creates a new termkey() instance with no file
25 handle associated. As this is usually done for handling other sources
26 of terminal byte input, it also takes a string indicating the termtype
27 to use.
28 termkey_destroy() destroys the given instance and releases any
30 resources controlled by it. It will not close the underlying filehandle
31 given as the fd argument to termkey_new().
32 The constructor attempts to detect if the current locale is UTF-8 aware
34 or not, and sets either the TERMKEY_FLAG_UTF8 or TERMKEY_FLAG_RAW flag.
35 One of these two bits will always be in effect. The current flags in
36 effect can be obtained by termkey_get_flags(3).
37 If a file handle is provided, the terminfo driver may send a string to
39 initialise or set the state of the terminal before termkey_new()
40 returns. This will not be done if no file handle is provided, or if the
41 file handle is a pipe (S_ISFIFO()). In this case it will be the call‐
42 er's responsibility to ensure the terminal is in the correct mode. Once
43 initialised, the terminal can be stopped by termkey_stop(3), and
44 started again by termkey_start(3).
45 This behaviour is modified by the TERMKEY_FLAG_NOSTART flag. If passed
47 in the flags argument then the instance will not be started yet by the
48 constructor; the caller must invoke termkey_start() at some future
49 point before the instance will be usable.
50
52 Before calling any functions in the termkey library, an application
53 should use the TERMKEY_CHECK_VERSION macro to check that the loaded
54 version of the library is compatible with the version it was compiled
55 against. This should be done early on, ideally just after entering its
56 main() function.
57
59 If successful, termkey_new() returns a pointer to the new instance. On
60 failure, NULL is returned with errno set to indicate the failure.
61 termkey_destroy() returns no value.
62
64 ENOENT No driver was able to recognise the given terminal type.
65 ENOMEM A call to malloc(3) failed to allocate memory.
67 Additionally, termkey_new() may fail if fstat(2) or write(2) fails on
69 the given file handle.
70
72 termkey_waitkey(3), termkey_advisereadable(3), termkey_getkey(3),
73 termkey_get_flags(3), termkey_get_fd(3), termkey_get_buffer_remain‐
74 ing(3), termkey_get_buffer_size(3), termkey(7)
75 TERMKEY_NEW(3)