---
name: "form"
section: "3x"
platform: "macos"
package: "ncurses"
version: "79"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/form/3x"
---

# form(3x)

curses extension for programming forms

## NAME

**form** - curses extension for programming forms

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

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

- **E\_UNKNOWN\_COMMAND**

  The form driver code saw an unknown request code.

## NOTES

The header file **\<form.h\>** automatically includes the header files **\<curses.h\>** and **\<eti.h\>**.

In your library list, libform.a should be before libncurses.a; that is, you want to say \`-lform -lncurses', not the other way around (which would give you a link error using most linkers).

## PORTABILITY

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

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

This describes **ncurses** version @NCURSES\_MAJOR@.@NCURSES\_MINOR@ (patch @NCURSES\_PATCH@).