field_new(3FORM)

💖 field_new — bestie, we're making FIELDS 💖

okay so this is field_new(3FORM), a library call from the forms corner of ncurses, and it's literally the whole "make a field, clone a field, yeet a field" starter pack. no cap.

---

✨ NAME ✨

new_field, dup_field, link_field, free_field — the four functions that create and destroy form fields. birth, photocopy, shared-custody copy, and goodbye 💅

---

🌸 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 🦋

new_field — the birth scene 👑

new_field allocates a brand-new field and initializes it straight from the parameters you handed over: height, width, the toprow of the upper-left corner, the leftcol of the upper-left corner, the number of off-screen rows, and the number of additional working buffers. it's giving "custom order, made fresh" ✨

dup_field — the clone 💖

dup_field duplicates a field at a new location. and bestie, it copies a LOT — most attributes, including:

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

what it does NOT copy: the field status and the field page bit. those stay behind, sorry babe 🙈

link_field — the clone that shares 🫶

link_field acts like dup_field, BUT the new field shares buffers with its parent. the attribute data stays separate though. so like, same brain cell, different personality. iconic.

free_field — the goodbye 💀

free_field de-allocates the storage associated with a field. releasing her into the wild. 🕊️

---

⭐ 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. bestie what did you type.
• E_SYSTEM_ERROR — system error occurred, e.g., malloc failure. the machine said no.

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. she's taken, you can't just free her like that. 🚫

---

🌈 PORTABILITY 🌈

these routines emulate the System V forms library. they were not supported on Version 7 or BSD versions. so like, vintage-only energy, iykyk.

and lowkey — 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 don't be shocked if another system does it differently, fr fr. 💀

---

👑 AUTHORS 👑

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

---

💜 SEE ALSO 💜

• ncurses(3NCURSES)
• form(3FORM)

---

and that's the whole page bestie!! this was field_new(3FORM) from ncurses 6.6, dated 2024-12-28 — go forth and build fields, you're the main character now 💅✨🌸