form_field_new(3X)

💖 form_field_new(3X) — bestie edition 💖

Library calls ✨ so this is the one about making and unmaking form fields, iykyk.

---

🌸 NAME 🌸

new_field, dup_field, link_field, free_field — create and destroy form fields 🎀

---

✨ 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);

---

🦋 DESCRIPTION 🦋

Okay so new_field is the main character here 👑 — it allocates a brand new field and initializes it from the parameters you hand it: height, width, the row of the upper-left corner, the column of the upper-left corner, the number of off-screen rows, and the number of additional working buffers. That's the whole vibe check. 💅

Then dup_field — it duplicates a field at a new location, no cap. Most attributes get copied over, and bestie that list is long: current contents, size, validation type, buffer count, growth threshold, justification, foreground, background, pad character, options, and user pointer. All of it, copied. 😌

But NOT everything, and this is important: field status and the field page bit are not copied. 🙈

link_field acts like dup_field, but with a twist 🧚 — the new field shares buffers with its parent. The attribute data, though? Separate. Independent. Living its own life. ✨

And free_field de-allocates the storage associated with a field. Bye babe 🫶

---

💀 RETURN VALUE 💀

new_field, dup_field, and link_field return NULL on error, and they set errno according to their success:

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

And free_field returns one of these:

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

---

🌈 PORTABILITY 🌈

These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions — so if you're on one of those, that's a no from the universe. 🙅

Also, ngl, 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… don't build your whole personality on it. 😬

---

👑 AUTHORS 👑

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

---

🍓 SEE ALSO 🍓

curses(3X), form(3X) — go read those next bestie, they're giving lore 📚

---

Okay that's the whole page!! This was ncurses 6.6, dated 2024-12-28 — mwah, kissing you goodbye 💋💜