menu_new(3MENU)

💖 menu_new — creating and destroying menu items, bestie edition

okay so we're in the 3MENU manual, section 3, library calls, and this page is literally the origin story of every menu item you will ever make. buckle up 🎀

---

✨ NAME ✨

new_item, free_item — the two functions that birth a menu item and then send it to the shadow realm. creation and destruction, main character energy fr fr 💅

---

🌸 SYNOPSIS 🌸

#include <menu.h>

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

look at them. two little icons. one makes, one takes away. balance 🦋

---

💜 DESCRIPTION 💜

so new_item allocates a brand new item and initializes it from the name and description pointers. sounds simple right? bestie. listen. 👑

the item only stores the pointers to the name and description. not copies. pointers. so those pointers have to stay valid for the entire lifetime of the item. the whole time. no cap. 😭

that means you should be very careful with names or descriptions allocated on the stack of some routines — because the second that stack frame dips out, your pointers are pointing at vibes and nothing else 💀

and then free_item de-allocates an item. but heads up, queen: it is the responsibility of the application to release the memory for the name or the description of the item. free_item is not doing that for you. it's giving "you're on your own for the strings, bestie" 🫶

---

⭐ RETURN VALUE ⭐

new_item returns NULL on error. yes, NULL. and it sets errno according to how it failed:

• E_BAD_ARGUMENT — the routine detected an incorrect or out-of-range argument. like, it looked at what you passed and said "no ❤️"
• E_SYSTEM_ERROR — a system error occurred, e.g., malloc failure. the system simply was not having it today 😔

and free_item returns one of these:

• E_OK — the routine succeeded. slay! we love a clean exit ✨
• E_BAD_ARGUMENT — routine detected an incorrect or out-of-range argument.
• E_CONNECTED — the item is connected to a menu. you cannot just free a whole item while it's still in a relationship with a menu, that's messy 🙈
• E_SYSTEM_ERROR — a 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. so if you're on an ancient BSD situation... it's not giving. it's not giving at all 💀

---

👑 AUTHORS 👑

Juergen Pfeifer. and the manual pages and adaptation for new curses were done by Eric S. Raymond. legends, honestly. we stan 🌟

---

🦋 SEE ALSO 🦋

• ncurses(3NCURSES)
• menu(3MENU)

---

and that's the whole page, bestie!! this was ncurses 6.6, dated 2024-12-28, and it's the menu_new(3MENU) manual — go forth and allocate responsibly, and please, PLEASE keep your string pointers alive 🎀✨💖