TERMKEY\_NEW(3) Library Functions Manual TERMKEY\_NEW(3)

# [NAME](#NAME)

termkey\_new, termkey\_destroy - create or destroy new termkey instance

# [SYNOPSIS](#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](#DESCRIPTION)

**termkey\_new**() creates a new [**termkey**(7)](/man/os/libtermkey/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)](/man/os/libtermkey/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)](/man/os/libtermkey/termkey_stop.3), and started again by [**termkey\_start**(3)](/man/os/libtermkey/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](#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](#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](#ERRORS)

[**ENOENT**](#ENOENT)

No driver was able to recognise the given terminal type.

[**ENOMEM**](#ENOMEM)

A call to [**malloc**(3)](/man/os/libtermkey/malloc.3) failed to allocate memory.

Additionally, **termkey\_new**() may fail if [**fstat**(2)](/man/os/libtermkey/fstat.2) or [**write**(2)](/man/os/libtermkey/write.2) fails on the given file handle.

# [SEE ALSO](#SEE_ALSO)

[**termkey\_waitkey**(3)](/man/os/libtermkey/termkey_waitkey.3), [**termkey\_advisereadable**(3)](/man/os/libtermkey/termkey_advisereadable.3), [**termkey\_getkey**(3)](/man/os/libtermkey/termkey_getkey.3), [**termkey\_get\_flags**(3)](/man/os/libtermkey/termkey_get_flags.3), [**termkey\_get\_fd**(3)](/man/os/libtermkey/termkey_get_fd.3), [**termkey\_get\_buffer\_remaining**(3)](/man/os/libtermkey/termkey_get_buffer_remaining.3), [**termkey\_get\_buffer\_size**(3)](/man/os/libtermkey/termkey_get_buffer_size.3), [**termkey**(7)](/man/os/libtermkey/termkey.7)

---

Document: termkey_new(3) from libtermkey 0.22-r8 (Chainguard OS)