form_field_new(3X)

💅 form_field_new(3X) — or, how to birth and yeet a form field

okay so bestie, this is a page from the ncurses manual set (it's the 3X library section, iykyk) and it's literally all about making fields and unmaking fields. Four little functions, one big vibe. Let's get into it 🎀

---

✨ NAME ✨

new_field, dup_field, link_field, free_field — create and destroy form fields. That's it, that's the whole gig: you make 'em, you copy 'em, you link 'em, you free 'em. 👑

---

🌸 SYNOPSIS 🌸

#include <form.h>

FIELD *new_field(int height, int width,
                 int toprow, int leftcol,
                 int offscreen, int nbuffers);
FIELD *dup_field(FIELD *field, int toprow, int leftcol);
FIELD *link_field(FIELD *field, int toprow, int leftcol);
int free_field(FIELD *field);

like, copy that #include <form.h> exactly or nothing works, no cap 💀

---

🦋 DESCRIPTION 🦋

🌈 new_field

new_field allocates a brand-new field and initializes it from the parameters you hand it: height, width, row of upper-left corner, column of upper-left corner, number off-screen rows, and number of additional working buffers. Six numbers, one fresh field. It's giving main character energy ✨

🎀 dup_field

dup_field duplicates a field at a new location. Most attributes are copied — and bestie when I say most, I mean the list is long:

• current contents
• size
• validation type
• buffer count
• growth threshold
• justification
• foreground
• background
• pad character
• options
• user pointer

But not everything, okay? Field status and the field page bit are not copied. Those two stay home. 🙈

💜 link_field

link_field acts like dup_field, but the new field shares buffers with its parent — attribute data is separate though. So they're linked at the buffer level but their vibes/attrs are their own. It's giving siblings who share a closet but not a personality 🫶

⭐ free_field

free_field de-allocates storage associated with a field. Cleanup era. Say bye 👋

---

🔥 RETURN VALUE 🔥

new_field, dup_field, and link_field return NULL on error. They set errno according to their success (yes, that phrasing is a little unhinged, but it's what the page says, and we respect the lore):

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

The function free_field returns one of the following:

• E_OK — the routine succeeded.
• E_BAD_ARGUMENT — routine detected an incorrect or out-of-range argument.
• E_CONNECTED — field is connected.

⚠️ heads up: E_CONNECTED means the field is still connected to something, so it's not getting freed. Don't fight it, just disconnect first bestie 😭

---

🧚 PORTABILITY 🧚

These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions — so if you're on ancient territory, this is not your era, sorry 💀

it may be unwise to count on the set of attributes copied by dup_field being portable; the System V forms library documents are not very explicit about what gets copied and what does not.

so like… fr fr, don't build your whole personality on that assumption. lowkey risky. 🙈

---

👑 AUTHORS 👑

Juergen Pfeifer. Manual pages and adaptation for new curses by Eric S. Raymond. legends, honestly 🫶

---

💖 SEE ALSO 💖

• curses(3X)
• form(3X)

---

and that's the page, bestie — brought to you by ncurses 6.5, dated 2024-12-28. go forth and create fields responsibly 🌸💅✨