---
name: "form"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/form/3"
---

# form(3)

present user-fillable forms in curses windows

## NAME

**form** - present user-fillable forms in *curses* windows

## SYNOPSIS

```
#include <form.h>
```

## DESCRIPTION

**The form library provides terminal-independent facilities for composing** **form screens on character-cell terminals.** **The library includes: field** **routines, which create and modify form fields; and 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.**

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

     **setlocale(LC\_ALL, "");**

**so that input/output processing will work.**

**A curses initialization routine such as initscr must be called** **before using any of these functions.**

### 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.** **Changing this default with a** **set\_ function affects future field creations, but does not change the** **rendering of fields already created.**

### Routine Name Index

**The following table lists each form routine and the name of** **the manual page on which it is described.** **Routines flagged with “\*”** **are** *ncurses***-specific, not present in SVr4.**

| | |
| --- | --- |
| **curses** Routine Name | Manual Page Name |
| 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

**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 the following error codes:**

- **E\_OK**

  **The routine succeeded.**

- **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)](/errno/3.md)).**

- **E\_UNKNOWN\_COMMAND**

  **The form driver code saw an unknown request code.**

## NOTES

**The header file** *form.h* **itself includes** *curses.h***.**

## 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:**

- •

  **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.**

## SEE ALSO

**curses(3X) and related pages whose names begin “form\_” for** **detailed descriptions of the entry points.**