menu_new(3X)

📦
version 6.6_p20260516 · 6 versions
, in alpine 3.24, arch rolling, fedora 44

okay so we're in menu_new(3X), the Library Calls girlies, and today's topic is literally just making and unmaking menus. creation and destruction. the full circle of life 💖

🌸 NAME 🌸

new_menu, free_menu — spin up a menu, and then (gently) let it go 🦋

✨ SYNOPSIS ✨

#include <menu.h>

MENU *new_menu(ITEM **items);
int free_menu(MENU *menu);

like… two functions. that's it. we're so back.

💅 DESCRIPTION 💅

okay so new_menu does exactly what it says on the tin: it creates a brand-new menu, and it hooks that menu up to an item pointer array you hand it. and bestie, hear me — that array must be NULL-terminated. not optional. not "ehh probably fine". NULL-terminated. periodt.

and then free_menu? she's the cleanup crew 🧹 she disconnects menu from its item array and frees up the storage that was allocated for the menu. no loose ends, no memory leaks, we love a responsible queen.

🫶 RETURN VALUE 🫶

new_menu returns NULL on error (not me getting nothing back 😭) and it sets errno based on what went wrong:

  • E_NOT_CONNECTED — there are literally no items connected to the menu. she's empty. nothing to work with.
  • E_SYSTEM_ERROR — a system error happened, like, say, a malloc failure. tragic.

free_menu returns one of these:

  • E_OK — the routine succeeded. we ate. 👑
  • E_SYSTEM_ERROR — a system error occurred (go peek at errno(3) for the deets).
  • E_BAD_ARGUMENT — the routine caught an argument that was incorrect or out of range. 🚩
  • E_POSTED — the menu has already been posted. she's out there. you can't do this rn.

🌈 PORTABILITY 🌈

these routines are out here emulating the System V menu library. iconic behavior, honestly. but heads up: they were not supported on Version 7 or BSD versions. so if you're on those, it's giving… unsupported. 💀

💜 AUTHORS 💜

Juergen Pfeifer. and the manual pages + adaptation for new curses were done by Eric S. Raymond. credit where credit is due, we respect the OGs 🎀

🎀 SEE ALSO 🎀

  • curses(3X)
  • menu(3X)

and that's the whole vibe ✨ this was menu_new(3X) from ncurses 6.6, dated 2024-12-28 — go forth, make menus, free them responsibly, and don't leak memory bestie, i'm begging 🫶💖

📦 where this page comes from