---
name: "termkey_new"
section: "3"
platform: "linux"
package: "libtermkey-dev"
version: "0.22-2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/termkey_new"
---

# termkey\_new(3)

create or destroy new termkey instance

## 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)](/termkey/7.md) 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)](/termkey_start/3.md).

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)](/malloc/3.md) failed to allocate memory.

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

## SEE ALSO

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