form(3FORM)

✨ form(3FORM) ✨

okay bestie, sit down, hydrate, because today we're talking about form — the Library calls girlie who presents user-fillable forms in curses windows. yes, forms. like, actual input fields. in a terminal. it's giving 1993 but make it slay 💅

---

🌸 NAME 🌸

form — present user-fillable forms in curses windows 🎀

---

🦋 SYNOPSIS 🦋

#include <form.h>

that's it. that's the whole synopsis. iconic of her tbh ✨

---

💖 DESCRIPTION 💖

The form library provides terminal-independent facilities for composing form screens on character-cell terminals. no cap, it does not care what terminal you're on, she will show up and she will render.

The library includes two whole friend groups:

• field routines, which create and modify form fields ✏️
• form routines, which group fields into forms, display forms on the screen, and handle interaction with the user 👑

The form library uses the curses libraries. To use the form library, link with the options -lform -lcurses. do not forget these, bestie, or you will get the saddest little linker errors of your life 😭

Your program should set up the locale, e.g.,

setlocale(LC_ALL, "");

so that input/output processing will work. fr fr, set your locale.

A curses initialization routine such as initscr must be called before using any of these functions. like, initscr first, then the form stuff. that's the order. periodt.

🌟 Current Default Values for Field Attributes 🌟

The form library maintains 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. yes, NULL` is the secret handshake.

changing this default with a set_ function affects future field creations, but does not change the rendering of fields already created. the old fields said "I'm not changing for anybody" 💀

🎀 Routine Name Index 🎀

here's the whole roster, bestie. every form routine and the manual page where it's described. routines flagged with a “*” are ncurses-specific, not present in SVr4 — so if you're on some other implementation, don't come crying to me about those ones 🙈

• current_field — page(3FORM)
• data_ahead — data(3FORM)
• data_behind — data(3FORM)
• dup_field — field_new(3FORM)
• dynamic_field_info — field_info(3FORM)
• field_arg — field_validation(3FORM)
• field_back — field_attributes(3FORM)
• field_buffer — field_buffer(3FORM)
• field_count — field(3FORM)
• field_fore — field_attributes(3FORM)
• field_index — page(3FORM)
• field_info — field_info(3FORM)
• field_init — hook(3FORM)
• field_just — field_just(3FORM)
• field_opts — field_opts(3FORM)
• field_opts_off — field_opts(3FORM)
• field_opts_on — field_opts(3FORM)
• field_pad — field_attributes(3FORM)
• field_status — field_buffer(3FORM)
• field_term — hook(3FORM)
• field_type — field_validation(3FORM)
• field_userptr — field_userptr(3FORM)
• form_driver — driver(3FORM)
• form_driver_w — driver(3FORM) *
• form_fields — field(3FORM)
• form_init — hook(3FORM)
• form_opts — opts(3FORM)
• form_opts_off — opts(3FORM)
• form_opts_on — opts(3FORM)
• form_page — page(3FORM)
• form_request_by_name — requestname(3FORM) *
• form_request_name — requestname(3FORM) *
• form_sub — win(3FORM)
• form_term — hook(3FORM)
• form_userptr — userptr(3FORM)
• form_win — win(3FORM)
• free_field — field_new(3FORM)
• free_fieldtype — fieldtype(3FORM)
• free_form — new(3FORM)
• link_field — field_new(3FORM)
• link_fieldtype — fieldtype(3FORM)
• move_field — field(3FORM)
• new_field — field_new(3FORM)
• new_fieldtype — fieldtype(3FORM)
• new_form — new(3FORM)
• new_page — new_page(3FORM)
• pos_form_cursor — cursor(3FORM)
• post_form — post(3FORM)
• scale_form — win(3FORM)
• set_current_field — page(3FORM)
• set_field_back — field_attributes(3FORM)
• set_field_buffer — field_buffer(3FORM)
• set_field_fore — field_attributes(3FORM)
• set_field_init — hook(3FORM)
• set_field_just — field_just(3FORM)
• set_field_opts — field_opts(3FORM)
• set_field_pad — field_attributes(3FORM)
• set_field_status — field_buffer(3FORM)
• set_field_term — hook(3FORM)
• set_field_type — field_validation(3FORM)
• set_field_userptr — field_userptr(3FORM)
• set_fieldtype_arg — fieldtype(3FORM)
• set_fieldtype_choice — fieldtype(3FORM)
• set_form_fields — field(3FORM)
• set_form_init — hook(3FORM)
• set_form_opts — field_opts(3FORM)
• set_form_page — page(3FORM)
• set_form_sub — win(3FORM)
• set_form_term — hook(3FORM)
• set_form_userptr — userptr(3FORM)
• set_form_win — win(3FORM)
• set_max_field — field_buffer(3FORM)
• set_new_page — new_page(3FORM)
• unfocus_current_field — page(3FORM) *
• unpost_form — post(3FORM)

75 entries. she's thorough. we respect it 🫶

---

🔥 RETURN VALUE 🔥

Routines that return pointers return NULL on error, and set errno to the corresponding error-code returned by functions returning an integer. so: pointer girls give you NULL, and they whisper the real tea into errno.

Routines that return an integer return one of the following error codes:

• E_OK — The routine succeeded. slay ✨
• E_BAD_ARGUMENT — Routine detected an incorrect or out-of-range argument. you passed her something cursed 💀
• E_BAD_STATE — Routine was called from an initialization or termination function. wrong place, wrong time, bestie.
• E_CONNECTED — The field is already connected to a form. she's taken 🙈
• E_INVALID_FIELD — Contents of a field are not valid. that data is not passing the vibe check.
• E_NOT_CONNECTED — No fields are connected to the form. the group chat is empty 😭
• E_NOT_POSTED — The form has not been posted. nothing to see here yet.
• E_NO_ROOM — Form is too large for its window. she does not fit, no matter how much she sucks in.
• E_POSTED — The form is already posted. she's out there living her life already.
• 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 💜

The header file form.h itself includes curses.h. so you don't have to, but you can. she's self-sufficient like that 👑

---

🌈 PORTABILITY 🌈

These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. so if you're time-traveling to ancient Unix, pack your own forms.

A form facility was documented in SVr4.2's Character User Interface Programming document. she has receipts 📜

It is not part of X/Open Curses. nope. not on the list.

Aside from ncurses, there are few implementations:

• 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. those two are ncurses originals, iykyk ✨

---

👑 AUTHORS 👑

Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S. Raymond.

(the legends themselves. we say thank you 🫶)

---

⭐ SEE ALSO ⭐

ncurses(3NCURSES) and related pages whose names begin “form_” for detailed descriptions of the entry points. go read those next, bestie, that's where the actual deep lore lives 📚

---

and that's the whole page!! mwah 💋 this was ncurses 6.6, dated 2025-11-11, and it's the form(3FORM) manual page — go build something cute with it, you're gonna do great 🎀💖🦋