mitem_new(3X)

💅 mitem_new — the curses menu-item origin story 🎀

okay so this is the mitem_new(3X) page from the library calls section, and it's literally about making and unmaking menu items. bestie, it's giving "birth and death of an ITEM" and honestly? iconic.

---

✨ NAME ✨

new_item, free_item — create and destroy menu items 🦋

---

🌸 SYNOPSIS 🌸

#include <menu.h>

ITEM *new_item(const char *name, const char *description);
int free_item(ITEM *item);

---

💖 DESCRIPTION 💖

so new_item allocates a brand-new item and initializes it from the name and description pointers. cute, right? but here's the catch, and it's a big one — the item stores ONLY the pointers to the name and description. it does not copy the strings. it does not clone them. it just… holds onto your pointers like a bestie holding your hand 🫶.

those pointers must be valid for the entire lifetime of the item. so like, be SO careful with names or descriptions that are allocated on the stack of some routine, because the moment that routine returns, your item is holding a pointer to a ghost 👻 and that's a whole situation you do not want.

free_item de-allocates an item. and ngl, this part is on you: it is the responsibility of the application to release the memory for the name or the description of the item. free_item frees the ITEM, not your strings. those are yours to manage, bestie, no cap 💅.

---

⭐ RETURN VALUE ⭐

new_item returns NULL on error 😭 and sets errno according to whatever went wrong:

• E_BAD_ARGUMENT — routine detected an incorrect or out-of-range argument.
• E_SYSTEM_ERROR — system error occurred, e.g., malloc failure 💀.

then free_item returns one of these:

• E_OK — the routine succeeded ✨ periodt.
• E_BAD_ARGUMENT — routine detected an incorrect or out-of-range argument.
• E_CONNECTED — item is connected to a menu 🙈 (so like, you can't just free it while it's still linked up, that's messy).
• E_SYSTEM_ERROR — system error occurred (see errno(3)).

---

🧚 PORTABILITY 🧚

these routines emulate the System V menu library. they were not supported on Version 7 or BSD versions. iykyk 🦋.

---

👑 AUTHORS 👑

Juergen Pfeifer. manual pages and adaptation for new curses by Eric S. Raymond. absolute main characters, we stan 🌈.

---

🔥 SEE ALSO 🔥

curses(3X), menu(3X)

---

okay that's the whole page, mwah 💋 — this one's from ncurses 6.5, dated 2024-12-28, so you know it's fresh 🍓. go forth and manage your pointers responsibly, bestie 💜