form(3X)

✨ NAME ✨

form — present user-fillable forms in curses windows 🎀

---

🦋 SYNOPSIS 🦋

#include <form.h>

---

💅 DESCRIPTION 💅

okay bestie, listen. the form library is literally the whole reason you can build terminal-independent form screens on character-cell terminals. it's giving ✨structured input✨ and we are obsessed.

it comes with two whole flavors of routines:

• field routines — they create and modify form fields
• form routines — they group fields into forms, display forms on the screen, and handle interaction with the user

the form library uses the curses libraries. so to use it, you link with the options -lform -lcurses. no cap, if you skip that you get nothing.

your program should set up the locale, like:

setlocale(LC_ALL, "");

so that input/output processing will work. it's literally the vibe check for your text.

also, a curses initialization routine such as initscr must be called before using any of these functions. like, before. not after. before. 🫶

🌸 Current Default Values for Field Attributes 🌸

the form library keeps a default value for field attributes. you can get or set this default by calling the appropriate set_ or retrieval routine with a NULL field pointer.

here's the tea though: changing this default with a set_ function affects future field creations, but does not change the rendering of fields already created. periodt.

👑 Routine Name Index 👑

this is the master list of every form routine and the manual page where it lives. routines flagged with * are ncurses-specific, not present in SVr4. iykyk.

• current_field → form_page(3X)
• data_ahead → form_data(3X)
• data_behind → form_data(3X)
• dup_field → form_field_new(3X)
• dynamic_field_info → form_field_info(3X)
• field_arg → form_field_validation(3X)
• field_back → form_field_attributes(3X)
• field_buffer → form_field_buffer(3X)
• field_count → form_field(3X)
• field_fore → form_field_attributes(3X)
• field_index → form_page(3X)
• field_info → form_field_info(3X)
• field_init → form_hook(3X)
• field_just → form_field_just(3X)
• field_opts → form_field_opts(3X)
• field_opts_off → form_field_opts(3X)
• field_opts_on → form_field_opts(3X)
• field_pad → form_field_attributes(3X)
• field_status → form_field_buffer(3X)
• field_term → form_hook(3X)
• field_type → form_field_validation(3X)
• field_userptr → form_field_userptr(3X)
• form_driver → form_driver(3X)
• form_driver_w → form_driver(3X) *
• form_fields → form_field(3X)
• form_init → form_hook(3X)
• form_opts → form_opts(3X)
• form_opts_off → form_opts(3X)
• form_opts_on → form_opts(3X)
• form_page → form_page(3X)
• form_request_by_name → form_requestname(3X) *
• form_request_name → form_requestname(3X) *
• form_sub → form_win(3X)
• form_term → form_hook(3X)
• form_userptr → form_userptr(3X)
• form_win → form_win(3X)
• free_field → form_field_new(3X)
• free_fieldtype → form_fieldtype(3X)
• free_form → form_new(3X)
• link_field → form_field_new(3X)
• link_fieldtype → form_fieldtype(3X)
• move_field → form_field(3X)
• new_field → form_field_new(3X)
• new_fieldtype → form_fieldtype(3X)
• new_form → form_new(3X)
• new_page → form_new_page(3X)
• pos_form_cursor → form_cursor(3X)
• post_form → form_post(3X)
• scale_form → form_win(3X)
• set_current_field → form_page(3X)
• set_field_back → form_field_attributes(3X)
• set_field_buffer → form_field_buffer(3X)
• set_field_fore → form_field_attributes(3X)
• set_field_init → form_hook(3X)
• set_field_just → form_field_just(3X)
• set_field_opts → form_field_opts(3X)
• set_field_pad → form_field_attributes(3X)
• set_field_status → form_field_buffer(3X)
• set_field_term → form_hook(3X)
• set_field_type → form_field_validation(3X)
• set_field_userptr → form_field_userptr(3X)
• set_fieldtype_arg → form_fieldtype(3X)
• set_fieldtype_choice → form_fieldtype(3X)
• set_form_fields → form_field(3X)
• set_form_init → form_hook(3X)
• set_form_opts → form_field_opts(3X)
• set_form_page → form_page(3X)
• set_form_sub → form_win(3X)
• set_form_term → form_hook(3X)
• set_form_userptr → form_userptr(3X)
• set_form_win → form_win(3X)
• set_max_field → form_field_buffer(3X)
• set_new_page → form_new_page(3X)
• unfocus_current_field → form_page(3X) *
• unpost_form → form_post(3X)

---

💖 RETURN VALUE 💖

so, the rules here are simple and we love them:

routines that return pointers return NULL on error, and set errno to the corresponding error-code returned by functions returning an integer.

routines that return an integer return one of these error codes:

• E_OK — the routine succeeded. slay. 👑
• E_BAD_ARGUMENT — routine detected an incorrect or out-of-range argument.
• E_BAD_STATE — routine was called from an initialization or termination function.
• E_CONNECTED — the field is already connected to a form.
• E_INVALID_FIELD — contents of a field are not valid.
• E_NOT_CONNECTED — no fields are connected to the form.
• E_NOT_POSTED — the form has not been posted.
• E_NO_ROOM — form is too large for its window. 😭
• E_POSTED — the form is already posted.
• E_REQUEST_DENIED — the form driver could not process the request.
• E_SYSTEM_ERROR — system error occurred (see errno(3)).
• E_UNKNOWN_COMMAND — the form driver code saw an unknown request code.

---

🌈 NOTES 🌈

fun fact bestie: the header file form.h itself includes curses.h. it's giving self-sufficient. 💅

---

🧚 PORTABILITY 🧚

these routines emulate the System V forms library. they were not supported on Version 7 or BSD versions.

a form facility was documented in SVr4.2's Character User Interface Programming document.

it is not part of X/Open Curses.

aside from ncurses, there are few implementations, lowkey:

• systems based on SVr4 source code, e.g., Solaris.
• NetBSD curses.

a few functions in this implementation are extensions added for ncurses, but not provided by other implementations, e.g., form_driver_w, unfocus_current_field.

---

🫶 AUTHORS 🫶

Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S. Raymond. legends, honestly. 🌟

---

⭐ SEE ALSO ⭐

curses(3X) and related pages whose names begin “form_” for detailed descriptions of the entry points. go read them, they ate. 🔥

---

that's the whole page babes 💜 this was ncurses 6.6, dated 2025-11-11, and if you made it to the bottom of the routine index you're officially a main character. bye bestie, go build a form 🦋🎀✨