---
name: "form"
section: "3form"
platform: "linux"
package: "ncurses-doc"
version: "6.5+20250216-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/form/3form"
---

# form(3form)

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

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

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