TERMKEY_INTERPRET_STRING(3)

💖 TERMKEY_INTERPRET_STRING(3) 💖

okay bestie, welcome to the Library Functions Manual ✨ this one's short and sweet, no cap.

🌸 NAME 🌸

termkey_interpret_string — fetch that stored control string, periodt 💅

🦋 SYNOPSIS 🦋

#include <termkey.h>

TermKeyResult termkey_interpret_string(TermKey *tk, const TermKeyKey *key,
    const char **strp);

Link with -ltermkey.

✨ DESCRIPTION ✨

so here's the tea 🍓 — termkey_interpret_string() goes and grabs the string that's chillin' inside your TermKey instance, the one from the most recently received TERMKEY_TYPE_DCS or TERMKEY_TYPE_OSC event. that's the whole vibe.

but listen, this is the important part, i need you paying attention 🙈 — you gotta call this function ASAP after you get one of those string key events. like, immediately. specifically before you call termkey_getkey() or termkey_waitkey() again, because a subsequent call will overwrite the buffer space that's currently holding your string. your cute little string? gone. evaporated. it's giving expired 😭

so the string pointer, whose address you hand over in strp, gets set to point at the actual stored string inside the instance. the caller (that's you, bestie 🫶) is free to read that string — and yes it will be correctly NUL-terminated, we're not animals — but do NOT modify it. hands off. look with your eyes 👀

also you do not need to free() that pointer. put the malloc away. the containing TermKey instance handles all of that itself, it's very much the main character doing its own admin 💅

💀 RETURN VALUE 💀

if you pass it the most recent key event of type TERMKEY_TYPE_DCS or TERMKEY_TYPE_OSC, this function returns TERMKEY_RES_KEY and it will affect the variables whose pointers you passed in, exactly as described above. slay ✨

for other event types, or for stale events? it returns TERMKEY_RES_NONE, and its effects on any of those pointer variables are undefined. not "maybe", not "probably fine" — undefined. so don't go reading them and acting surprised, i warned you 😭

👑 SEE ALSO 👑

• termkey_waitkey(3)
• termkey_getkey(3)
• termkey(7)

and that's the whole page, no notes 💜 this was the TERMKEY_INTERPRET_STRING(3) page from the Library Functions Manual — go forth and interpret your strings before the buffer eats them, i'm obsessed with you, bye 🎀🦋