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

# curs\_attr(3x)

curses character and window attribute control routines

## NAME

**attroff**, **wattroff**, **attron**, **wattron**, **attrset**, **wattrset**, **color\_set**, **wcolor\_set**, **standend**, **wstandend**, **standout**, **wstandout**, **attr\_get**, **wattr\_get**, **attr\_off**, **wattr\_off**, **attr\_on**, **wattr\_on**, **attr\_set**, **wattr\_set**, **chgat**, **wchgat**, **mvchgat**, **mvwchgat**, **PAIR\_NUMBER** - **curses** character and window attribute control routines

## SYNOPSIS

**#include \<curses.h\>**\
 **int attroff(int** *attrs);*\
 **int wattroff(WINDOW \****win***, int** *attrs***);**\
 **int attron(int** *attrs***);**\
 **int wattron(WINDOW \****win***, int** *attrs***);**\
 **int attrset(int** *attrs***);**\
 **int wattrset(WINDOW \****win***, int** *attrs***);**\
 **int color\_set(short** *color\_pair\_number***, void\*** *opts***);**\
 **int wcolor\_set(WINDOW \****win***, short** *color\_pair\_number***,**\
       **void\*** *opts);*\
 **int standend(void);**\
 **int wstandend(WINDOW \****win***);**\
 **int standout(void);**\
 **int wstandout(WINDOW \****win***);**\
 **int attr\_get(attr\_t \****attrs***, short \****pair***, void \****opts***);**\
 **int wattr\_get(WINDOW \****win***, attr\_t \****attrs***, short \****pair***,**\
        **void \****opts***);**\
 **int attr\_off(attr\_t** *attrs***, void \****opts***);**\
 **int wattr\_off(WINDOW \****win***, attr\_t** *attrs***, void \****opts***);**\
 **int attr\_on(attr\_t** *attrs***, void \****opts***);**\
 **int wattr\_on(WINDOW \****win***, attr\_t** *attrs***, void \****opts***);**\
 **int attr\_set(attr\_t** *attrs***, short** *pair***, void \****opts***);**\
 **int wattr\_set(WINDOW \****win***, attr\_t** *attrs***, short** *pair***, void \****opts***);**\
 **int chgat(int** *n***, attr\_t** *attr***, short** *color***,**\
       **const void \****opts***);**\
 **int wchgat(WINDOW \****win***, int** *n***, attr\_t** *attr***,**\
       **short** *color***, const void \****opts***);**\
 **int mvchgat(int** *y***, int** *x***, int** *n***, attr\_t** *attr***,**\
       **short** *color***, const void \****opts***);**\
 **int mvwchgat(WINDOW \****win, int y, int x, int n,*\
       **attr\_t** *attr***, short** *color***, const void \****opts***);**\

## DESCRIPTION

These routines manipulate the current attributes of the named window. The current attributes of a window apply to all characters that are written into the window with **waddch**, **waddstr** and **wprintw**. Attributes are a property of the character, and move with the character through any scrolling and insert/delete line/character operations. To the extent possible, they are displayed as appropriate modifications to the graphic rendition of characters put on the screen.

### attrset

The routine **attrset** sets the current attributes of the given window to *attrs*. The routine **attroff** turns off the named attributes without turning any other attributes on or off. The routine **attron** turns on the named attributes without affecting any others. The routine **standout** is the same as **attron(A\_STANDOUT)**. The routine **standend** is the same as **attrset(A\_NORMAL)** or **attrset(0)**, that is, it turns off all attributes.

The **attrset** and related routines do not affect the attributes used when erasing portions of the window. See **curs\_bkgd**(3X) for functions which modify the attributes used for erasing and clearing.

### attr\_set

The **attrset** routine is actually a legacy feature predating SVr4 curses but kept in X/Open Curses for the same reason that SVr4 curses kept it: compatbility. The routine **attr\_set** provides for passing a color-pair parameter.

The remaining **attr\_**\* functions operate exactly like the corresponding **attr**\* functions, except that they take arguments of type **attr\_t** rather than **int**.

### color\_set

The routine **color\_set** sets the current color of the given window to the foreground/background combination described by the color\_pair\_number. The parameter opts is reserved for future use, applications must supply a null pointer.

### attr\_get

The routine **wattr\_get** returns the current attribute and color pair for the given window; **attr\_get** returns the current attribute and color pair for **stdscr**.

There is no corresponding **attrget** function as such in X/Open Curses, although ncurses provides **getattrs** (see [curs\_legacy(3x)](/curs_legacy/3x.md)).

### chgat

The routine **chgat** changes the attributes of a given number of characters starting at the current cursor location of **stdscr**. It does not update the cursor and does not perform wrapping. A character count of -1 or greater than the remaining window width means to change attributes all the way to the end of the current line. The **wchgat** function generalizes this to any window; the **mvwchgat** function does a cursor move before acting. In these functions, the color argument is a color-pair index (as in the first argument of *init\_pair*, see **curs\_color**(3X)). The **opts** argument is not presently used, but is reserved for the future (leave it **NULL**).

### Attributes

The following video attributes, defined in **\<curses.h\>**, can be passed to the routines **attron**, **attroff**, and **attrset**, or OR'd with the characters passed to **addch** (see [curs\_addch(3x)](/curs_addch/3x.md)).

| | |
| --- | --- |
| *Name* | *Description* |
|
| **A\_STANDOUT** | Best highlighting mode of the terminal. |
| **A\_UNDERLINE** | Underlining |
| **A\_REVERSE** | Reverse video |
| **A\_BLINK** | Blinking |
| **A\_DIM** | Half bright |
| **A\_BOLD** | Extra bright or bold |
| **A\_PROTECT** | Protected mode |
| **A\_INVIS** | Invisible or blank mode |
| **A\_ALTCHARSET** | Alternate character set |
| **A\_ITALIC** | Italics (non-X/Open extension) |
| **A\_CHARTEXT** | Bit-mask to extract a character |
| **COLOR\_PAIR(***n***)** | Color-pair number *n* |

These video attributes are supported by **attr\_on** and related functions (which also support the attributes recognized by **attron**, etc.):

| | |
| --- | --- |
| *Name* | *Description* |
|
| **WA\_LEFT** | Left highlight |
| **WA\_LOW** | Low highlight |
| **WA\_RIGHT** | Right highlight |
| **WA\_TOP** | Top highlight |
| **WA\_VERTICAL** | Vertical highlight |

For consistency

The following macro is the reverse of **COLOR\_PAIR(***n***)**:

**PAIR\_NUMBER(***attrs*) Returns the pair number associated\
                    with the **COLOR\_PAIR(***n***)** attribute.\

The return values of many of these routines are not meaningful (they are implemented as macro-expanded assignments and simply return their argument). The SVr4 manual page claims (falsely) that these routines always return **1**.

## NOTES

Note that **attroff**, **wattroff**, **attron**, **wattron**, **attrset**, **wattrset**, **standend** and **standout** may be macros.

**COLOR\_PAIR** values can only be OR'd with attributes if the pair number is less than 256. The alternate functions such as **color\_set** can pass a color pair value directly. However, ncurses ABI 4 and 5 simply OR this value within the alternate functions. You must use ncurses ABI 6 to support more than 256 color pairs.

## PORTABILITY

These functions are supported in the XSI Curses standard, Issue 4. The standard defined the dedicated type for highlights, **attr\_t**, which is not defined in SVr4 curses. The functions taking **attr\_t** arguments are not supported under SVr4.

The XSI Curses standard states that whether the traditional functions **attron**/**attroff**/**attrset** can manipulate attributes other than **A\_BLINK**, **A\_BOLD**, **A\_DIM**, **A\_REVERSE**, **A\_STANDOUT**, or **A\_UNDERLINE** is "unspecified". Under this implementation as well as SVr4 curses, these functions correctly manipulate all other highlights (specifically, **A\_ALTCHARSET**, **A\_PROTECT**, and **A\_INVIS**).

This implementation provides the **A\_ITALIC** attribute for terminals which have the *enter\_italics\_mode* (sitm) and *exit\_italics\_mode* (ritm) capabilities. Italics are not mentioned in X/Open Curses. Unlike the other video attributes, **I\_ITALIC** is unrelated to the *set\_attributes* capabilities. This implementation makes the assumption that *exit\_attribute\_mode* may also reset italics.

XSI Curses added the new entry points, **attr\_get**, **attr\_on**, **attr\_off**, **attr\_set**, **wattr\_on**, **wattr\_off**, **wattr\_get**, **wattr\_set**. These are intended to work with a new series of highlight macros prefixed with **WA\_**. The older macros have direct counterparts in the newer set of names:

| | |
| --- | --- |
| *Name* | *Description* |
|
| **WA\_STANDOUT** | Best highlighting mode of the terminal. |
| **WA\_UNDERLINE** | Underlining |
| **WA\_REVERSE** | Reverse video |
| **WA\_BLINK** | Blinking |
| **WA\_DIM** | Half bright |
| **WA\_BOLD** | Extra bright or bold |
| **WA\_ALTCHARSET** | Alternate character set |

Very old versions of this library did not force an update of the screen when changing the attributes. Use **touchwin** to force the screen to match the updated attributes.

The XSI curses standard specifies that each pair of corresponding **A\_** and **WA\_**-using functions operates on the same current-highlight information.

The XSI standard extended conformance level adds new highlights **A\_HORIZONTAL**, **A\_LEFT**, **A\_LOW**, **A\_RIGHT**, **A\_TOP**, **A\_VERTICAL** (and corresponding **WA\_** macros for each). As of August 2013, no known terminal provides these highlights (i.e., via the **sgr1** capability).

## RETURN VALUE

All routines return the integer **OK** on success, or **ERR** on failure.

X/Open does not define any error conditions.

This implementation returns an error if the window pointer is null. The **wcolor\_set** function returns an error if the color pair parameter is outside the range 0..COLOR\_PAIRS-1. This implementation also provides **getattrs** for compatibility with older versions of curses.

Functions with a "mv" prefix first perform a cursor movement using **wmove**, and return an error if the position is outside the window, or if the window pointer is null.

## SEE ALSO

**curses**(3X), **curs\_addch**(3X), **curs\_addstr**(3X), **curs\_bkgd**(3X), **curs\_printw**(3X), **curs\_variables**(3X)