new_pair(3X)

✨ new_pair — bestie's guide to dynamic color pairs 💖

okay so this is the new_pair(3X) page from the library calls section, and honestly? it's a glow-up for curses color handling. let's get into it 🫶

---

🌸 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 💅

okay so these three functions? they're an extension to the curses library. no cap. they let an application dynamically allocate a color pair using the foreground/background colors instead of assigning a fixed color pair number, and they hand an unused pair back to the pool. it's giving "let the library handle the bookkeeping, queen" 👑

now, the number of colors may be related to the number of possible color pairs for a given terminal — or it may not. it's complicated, and here's the tea:

• while almost all terminals let you set the color attributes independently, it's unlikely that your terminal lets you modify the attributes of a given character cell without rewriting it. translation: the foreground and background colors get applied as a pair. they're a package deal, fr fr 💞
• color pairs are the curses library's way of managing a color palette on a terminal. if the library doesn't keep track of the combinations of colors which are displayed, it will be inefficient. so it keeps track. she's organized 💅
• for simple terminal emulators with only a few dozen color combinations, it's 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). yes bestie, ASCII art counts as a use case 🌈

also beyond those few dozen pairs, the required size for a table to represent the combinations grows rapidly with an increasing number of colors. it's exponential-coded and not in a cute way 😭

these functions allow a developer to let the screen library manage color pairs. letting go and letting the library cook 🔥

🦋 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. here's the vibe check:

• if the combination already exists, alloc_pair returns the existing pair. found it, no need to make a new one 💖
• if the combination does not exist, alloc_pair allocates a new color pair and returns that. new pair, who dis ✨
• if the table fills up, alloc_pair discards the least-recently allocated entry using free_pair and allocates a new color pair. it's the circle of life, bestie, the oldest one gets evicted 🚪

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. and get this — 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. they're besties, they share everything 🫶

🌸 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. it's the "do you already have this?" friend, and if the answer is no, you get a -1 💀

🧚 free_pair 🧚

marks the given color pair as unused, i.e., like color pair 0. releasing it back into the wild 🌿

---

⭐ 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. OK is the good ending, periodt 💅

---

🌈 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. so guard that code, bestie, don't get caught slipping 🙈

---

👑 AUTHORS 👑

Thomas Dickey

---

💜 SEE ALSO 💜

curs_color(3X)

---

okay that's the whole page, you ate it up, no crumbs 💅 sending you off with the deets: this was ncurses 6.6, dated 2025-08-16, from the new_pair(3X) page. go forth and allocate your pairs dynamically, main character 🦋✨