TERMKEY_NEW(3)

💖 TERMKEY_NEW — the manual page for termkey_new(3), termkey_new_abstract(3) and termkey_destroy(3) 💖

okay bestie, welcome to the Library Functions Manual ✨ this is the one that teaches you how to make a termkey instance and how to yeet it when you're done 🎀

🌸 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);

and bestie, don't forget to Link with -ltermkey or nothing works 😭

🦋 DESCRIPTION 🦋

termkey_new() creates a brand new termkey(7) instance, and it's connected to the file handle that got opened by fd, using the flags. Now listen — the TermKey structure is opaque, okay? Its contents are literally not intended for use outside of the library 🙈 don't go poking at its insides, it's not that kind of relationship 💅

termkey_new_abstract() creates a new termkey() instance with no file handle associated at all. The way that 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. But IMPORTANT — it will not close the underlying filehandle you gave as the fd argument to termkey_new(). She's destroying herself, not your fd, periodt 💀

The constructor attempts to detect if the current locale is UTF-8 aware or not, and sets either the TERMKEY_FLAG_UTF8 or the TERMKEY_FLAG_RAW flag. One of these two bits will always be in effect — always, no cap. 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. That will not be done if no file handle is provided, or if the file handle is a pipe (S_ISFIFO()). In that case it's the caller's responsibility to make sure 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 you pass it 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. So like, she exists but she's not awake yet 😴

🎀 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 ✅

Do this early on, ideally just after entering its main() function. Like, first thing. Before the vibes get complicated 🌸

💜 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. She gives nothing back and that's fine 💅

🔥 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.

bestie fr fr, if you see one of these, it's giving "something went wrong upstream" — check your termtype and your fds 🫶

🌈 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)

and that's the whole page, bestie!! this was the TERMKEY_NEW(3) entry from the Library Functions Manual — go forth and construct your instances responsibly 💖✨🎀🦋