---
name: "new_pair"
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/new_pair"
---

# new\_pair(3)

dynamically allocate curses color pairs

## NAME

**alloc\_pair**, **find\_pair**, **free\_pair** - dynamically allocate *curses* color pairs

## SYNOPSIS

```
#include <curses.h>
```

**int alloc\_pair(int** *fg***, int** *bg***);** **int find\_pair(int** *fg***, int** *bg***);** **int free\_pair(int** *pair***);**

## DESCRIPTION

**These functions are an extension to the** *curses* **library.** **They permit an application to dynamically allocate a color pair using** **the foreground/background colors rather than assign a fixed color pair number,** **and return an unused pair to the pool.**

**The number of colors may be related to the number of possible color** **pairs for a given terminal, or it may not:**

- •

  **While almost all terminals allow setting the color** *attributes* **independently,** **it is unlikely that your terminal allows you to modify the attributes** **of a given character cell without rewriting it.** **That is, the foreground and background colors are applied as a pair.**

- •

  **Color pairs are the** *curses* **library's way of managing a color palette** **on a terminal.** **If the library does not keep track of the** *combinations* **of** **colors which are displayed, it will be inefficient.**

- •

  **For simple terminal emulators** **with only a few dozen color combinations,** **it is convenient to use the maximum number of combinations** **as the limit on color pairs:**

```
COLORS * COLORS
```

- •

  Terminals which support *default colors* distinct from “ANSI colors” add to the possible combinations, producing this total:

```
( COLORS + 1 ) * ( COLORS + 1 )
```

- •

  An application might use up to a few dozen color pairs to implement a color scheme.

-

  Beyond that lies in the realm of programs using the foreground and background colors for “ASCII art” (or some other non-textual application).

-

  Also beyond those few dozen pairs, the required size for a table to represent the combinations grows rapidly with an increasing number of colors.

-

  These functions allow a developer to let the screen library manage color pairs.

### alloc\_pair

The **alloc\_pair** function accepts parameters for foreground and background color, and checks whether that color combination is already associated with a color pair.

- •

  If the combination already exists, **alloc\_pair** returns the existing pair.

- •

  If the combination does not exist, **alloc\_pair** allocates a new color pair and returns that.

- •

  If the table fills up, **alloc\_pair** discards the least-recently allocated entry using **free\_pair** and allocates a new color pair.

All of the color pairs are allocated from a table of possible color pairs. The size of the table is determined by the terminfo **pairs** capability. The table is shared with **init\_pair**; in fact **alloc\_pair** calls **init\_pair** after updating the *ncurses* library's fast index to the colors versus color pairs.

### find\_pair

The **find\_pair** function accepts parameters for foreground and background color, and checks whether that color combination is already associated with a color pair, returning the pair number if it has been allocated. Otherwise it returns -1.

### free\_pair

Marks the given color pair as unused, i.e., like color pair 0.

## RETURN VALUE

The **alloc\_pair** function returns a color pair number in the range 1 through **COLOR\_PAIRS**-1, unless it encounters an error updating its fast index to the color pair values, preventing it from allocating a color pair. In that case, it returns -1.

The **find\_pair** function returns a color pair number if the given color combination has been associated with a color pair, or -1 if not.

Likewise, **free\_pair** returns **OK** unless it encounters an error updating the fast index or if no such color pair is in use.

## PORTABILITY

These routines are specific to *ncurses*. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using **NCURSES\_VERSION**.

## AUTHORS

Thomas Dickey

## SEE ALSO

**curs\_color**(3X)