Copyright (c) 2002 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Julian Coleman.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd July 27, 2021 .Dt CURSES_ATTRIBUTES 3 .Os .Sh NAME .Nm curses_attributes , .Nm attron , .Nm attroff , .Nm attrset , .Nm color_set , .Nm getattrs , .Nm termattrs , .Nm wattron , .Nm wattroff , .Nm wattrset , .Nm wcolor_set , .Nm attr_on , .Nm attr_off , .Nm attr_set , .Nm attr_get , .Nm term_attrs , .Nm wattr_on , .Nm wattr_off , .Nm wattr_set , .Nm wattr_get .Nd curses general attribute manipulation routines .Sh LIBRARY .Lb libcurses .Sh SYNOPSIS n curses.h .Ft int .Fn attron "int attr" .Ft int .Fn attroff "int attr" .Ft int .Fn attrset "int attr" .Ft int .Fn color_set "short pair" "void *opt" .Ft chtype .Fn getattrs "WINDOW *win" .Ft chtype .Fn termattrs "void" .Ft int .Fn wcolor_set "WINDOW *win" "short pair" "void *opt" .Ft int .Fn wattron "WINDOW * win" "int attr" .Ft int .Fn wattroff "WINDOW * win" "int attr" .Ft int .Fn wattrset "WINDOW * win" "int attr" .Ft int .Fn attr_on "attr_t attr" "void *opt" .Ft int .Fn attr_off "attr_t attr" "void *opt" .Ft int .Fn attr_set "attr_t attr" "short pair" "void *opt" .Ft int .Fn attr_get "attr_t *attr" "short *pair" "void *opt" .Ft attr_t .Fn term_attrs "void" .Ft int .Fn wattr_on "WINDOW *win" "attr_t attr" "void *opt" .Ft int .Fn wattr_off "WINDOW *win" "attr_t attr" "void *opt" .Ft int .Fn wattr_set "WINDOW *win" "attr_t attr" "short pair" "void *opt" .Ft int .Fn wattr_get "WINDOW *win" "attr_t *attr" "short *pair" "void *opt" .Sh DESCRIPTION These functions manipulate attributes on .Va stdscr or on the specified window. The attributes that can be manipulated are:
p l -tag -width "COLOR_PAIR(n)" -compact -offset indent t A_NORMAL no special attributes are applied t A_STANDOUT characters are displayed in the "best" supported highlighting mode of the terminal t A_UNDERLINE characters are displayed underlined t A_REVERSE characters are displayed in inverse video t A_BLINK characters blink t A_DIM characters are displayed at a lower intensity t A_BOLD characters are displayed at a higher intensity t A_INVIS characters are added invisibly t A_PROTECT characters are protected from modification t A_ALTCHARSET characters are displayed using the alternate character set (ACS) t COLOR_PAIR(n) characters are displayed using color pair n. .El
p The .Fn attron function turns on the attributes specified in .Fa attr on .Va stdscr , while the .Fn attroff function turns off the attributes specified in .Fa attr on .Va stdscr .
p The function .Fn attrset sets the attributes of .Va stdscr to those specified in .Fa attr , turning off any others. To turn off all the attributes (including color and alternate character set), use .Fn attrset A_NORMAL .
p Multiple attributes can be manipulated by combining the attributes using a logical .Em OR . For example, .Fn attron "A_REVERSE | A_BOLD" will turn on both inverse video and higher intensity.
p The function .Fn color_set sets the color pair attribute to the pair specified in .Fa pair .
p The function .Fn getattrs returns the attributes that are currently applied to window specified by .Fa win .
p The function .Fn termattrs returns the logical .Em OR of attributes that can be applied to the screen.
p The functions .Fn wattron , .Fn wattroff , .Fn wattrset , and .Fn wcolor_set are equivalent to .Fn attron , .Fn attroff .Fn attrset , and .Fn color_set respectively, excepting that the attributes are applied to the window specified by .Fa win .
p The following functions additionally manipulate wide attributes on .Va stdscr or on the specified window. The additional wide attributes that can be manipulated are:
p l -tag -width "COLOR_PAIR(n)" -compact -offset indent t WA_STANDOUT characters are displayed in the "best" supported highlighting mode of the terminal t WA_UNDERLINE characters are displayed underlined t WA_REVERSE characters are displayed in inverse video t WA_BLINK characters blink t WA_DIM characters are displayed at a lower intensity t WA_BOLD characters are displayed at a higher intensity t WA_INVIS characters are added invisibly t WA_PROTECT characters are protected from modification t WA_ALTCHARSET characters are displayed using the alternate character set (ACS) t WA_LOW characters are displayed with low highlight t WA_TOP characters are displayed with top highlight t WA_HORIZONTAL characters are displayed with horizontal highlight t WA_VERTICAL characters are displayed with vertical highlight t WA_LEFT characters are displayed with left highlight t WA_RIGHT characters are displayed with right highlight .El
p The .Fn attr_on function turns on the wide attributes specified in .Fa attr on .Va stdscr , while the .Fn attr_off function turns off the wide attributes specified in .Fa attr on .Va stdscr .
p The function .Fn attr_set sets the wide attributes of .Va stdscr to those specified in .Fa attr and .Fa pair , turning off any others. Note that a color pair specified in .Fa pair will override any color pair specified in .Fa attr .
p The function .Fn attr_get sets .Fa attr to the wide attributes and .Fa pair to the color pair currently applied to .Va stdscr . Either of .Fa attr and .Fa pair can be .Dv NULL , if the relevant value is of no interest.
p The function .Fn term_attrs returns the logical .Em OR of wide attributes that can be applied to the screen.
p The functions .Fn wattr_on , .Fn wattr_off and .Fn wattr_set are equivalent to .Fn attr_on , .Fn attr_off and .Fn attr_set respectively, excepting that the character is added to the window specified by .Fa win .
p The function .Fn wattr_get is equivalent to .Fn attr_get , excepting that the wide attributes and color pair currently applied to .Fa win are set.
p The following constants can be used to extract the components of a .Dv chtype :
p l -tag -width "COLOR_PAIR(n)" -compact -offset indent t A_ATTRIBUTES bit-mask containing attributes part t A_CHARTEXT bit-mask containing character part t A_COLOR bit-mask containing color-pair part .El .Sh RETURN VALUES These functions return OK on success and ERR on failure. .Sh SEE ALSO .Xr curses_addch 3 , .Xr curses_addchstr 3 , .Xr curses_addstr 3 , .Xr curses_background 3 , .Xr curses_color 3 , .Xr curses_insch 3 , .Xr curses_standout 3 , .Xr curses_underscore 3 .Sh NOTES The .Fa opt argument is not currently used but is reserved for a future version of the specification. .Sh STANDARDS The .Nx Curses library complies with the X/Open Curses specification, part of the Single Unix Specification.
p The .Fn getattrs function is a .Nx extension. .Sh HISTORY These functions first appeared in .Nx 1.5 . .Sh CAVEATS Some terminals do not support characters with both color and other attributes set. In this case, the other attribute is displayed instead of the color attribute.
p The standout attribute is a higher level alias and should not be mixed with other attributes.
Indexes created Sat Sep 20 22:09:52 GMT 2025