TT_MESSAGE_RECEIVE(3)

💌 tt_message_receive — receive a message

okay so this is a page from the library call manual set, and it's about tt_message_receive — the little function that grabs the next message off your process's queue. bestie, it's literally the mailbox moment. let's get into it ✨

✨ SYNOPSIS ✨

#include <Tt/tt_c.h>
Tt_message tt_message_receive(void)

that's it. no arguments. she takes nothing and gives you a handle. iconic behavior honestly 🎀

🌸 DESCRIPTION 🌸

The tt_message_receive function returns a handle for the next message queued to be delivered to the process, and — this is the part people forget — it also runs any message or pattern callbacks applicable to the queued message. so like, it's not just handing you the envelope, it's also opening the mail and doing the little chores that come with it. multitasking queen 💅

now, pay attention to this next bit because it's important:

• If the return value of tt_message_status(3) for this message is TT_WRN_START_MESSAGE, that means the ToolTalk service started the process to deliver the queued message — and the process must reply to this message. no ghosting allowed, fr fr. 😭
• If the return value of tt_message_receive is zero, no message is available. empty inbox energy. 📭

💖 RETURN VALUE 💖

Upon successful completion, the tt_message_receive function returns the handle for the message object. slay. ✨

The application can use tt_ptr_error(3) to extract one of the following Tt_status values from the returned handle:

• TT_OK — the operation completed successfully. we love a clean win. 👑
• TT_ERR_NOMP — the ttsession(1) process is not running and the ToolTalk service cannot restart it. 💀 that's the bad one. that's the "your session dipped and nobody can save her" one.

🦋 APPLICATION USAGE 🦋

A zero value can occur if a message or pattern callback processes the message. so sometimes zero doesn't mean "nothing there", it means "something there already got handled". sneaky.

It can also occur if the interval is too long between the time the file descriptor became active and the tt_message_receive call was made. In the latter case, the ToolTalk service will time out and offer the message to another process. 😬 so like… don't be slow, bestie. the message will literally get re-gifted to somebody else while you're staring at your file descriptor.

The application should use tt_free(3) to free any data stored in the address returned by the ToolTalk API. this is not optional-optional, it's memory-hygiene-optional, and you know how that ends. 🫶

🌈 SEE ALSO 🌈

• Tt/tt_c.h - Tttt_c(5)
• tt_ptr_error(3)
• tt_free(3)

---

and that's the page!! 🎀 this whole thing is the tt_message_receive entry out of the library call manual set — no fancy version stamp or date on this one, she's just vibing as tt_message_receive(library call) top and bottom, iykyk. go get those messages, bestie 💜🔥