Debian Codegraph @

upstream/debian-unstable/man3/termattrs.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,2015 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_termattrs.3x,v 1.61 2025/08/23 22:39:20 tom Exp $
31 .TH termattrs 3NCURSES 2025-08-23 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .SH NAME
43 \fB\%baudrate\fP,
44 \fB\%erasechar\fP,
45 \fB\%erasewchar\fP,
46 \fB\%has_ic\fP,
47 \fB\%has_il\fP,
48 \fB\%killchar\fP,
49 \fB\%killwchar\fP,
50 \fB\%longname\fP,
51 \fB\%term_attrs\fP,
52 \fB\%termattrs\fP,
53 \fB\%termname\fP \-
54 get and set terminal attributes with \fIcurses\fP
55 .SH SYNOPSIS
56 .nf
57 \fB#include <curses.h>
58 .PP
59 \fBint baudrate(void);
60 \fBchar erasechar(void);
61 \fBint erasewchar(wchar_t * \fIwc\fP);
62 \fBbool has_ic(void);
63 \fBbool has_il(void);
64 \fBchar killchar(void);
65 \fBint killwchar(wchar_t * \fIwc\fP);
66 \fBchar * longname(void);
67 \fBattr_t term_attrs(void);
68 \fBchtype termattrs(void);
69 \fBchar * termname(void);
70 .fi
71 .SH DESCRIPTION
72 .SS baudrate
73 .B \%baudrate
74 returns the line speed of the terminal,
75 an integer value measured in bits per second,
76 for example
77 .BR 9600 "."
78 .SS "erasechar, erasewchar"
79 .B \%erasechar
80 returns the terminal's erase character.
81 .PP
82 .B \%erasewchar
83 stores the erase character in the location referenced by
84 .IR wc "."
85 If no erase character has been defined,
86 it fails and the location referenced by
87 .I wc
88 is not changed.
89 .SS "has_ic, has_il"
90 .B \%has_ic
91 returns
92 .B TRUE
93 if the terminal has insert- and delete-character capabilities.
94 .PP
95 .B \%has_il
96 returns
97 .B TRUE
98 if the terminal has insert- and delete-line capabilities,
99 or can simulate them using scrolling regions.
100 It might be used to determine whether it would be appropriate
101 to use \fBscrollok\fP(3NCURSES) to turn on scrolling.
102 .SS "killchar, killwchar"
103 .B \%killchar
104 returns the terminal's line kill character.
105 .PP
106 .B \%killwchar
107 stores the line-kill character in the location referenced by
108 .IR wc "."
109 If no line-kill character has been defined,
110 it fails and the location referenced by
111 .I wc
112 is not changed.
113 .SS longname
114 .B \%longname
115 returns a pointer to static storage
116 containing a verbose description of the terminal being managed by
117 .IR curses "."
118 The maximum length of a verbose description is 128 characters.
119 The storage is populated only after \fBinitscr\fP(3NCURSES) or
120 \fBnewterm\fP(3NCURSES) is called.
121 This storage is overwritten by each call to
122 .B \%newterm
123 and not restored by \fBset_term\fP(3NSES),
124 so its contents should be saved between calls to
125 .B \%initscr
126 or
127 .B \%newterm
128 if
129 .B \%longname
130 is to be used with multiple terminals.
131 .SS "termattrs, term_attrs"
132 If a given terminal does not support a video attribute that an
133 application program is trying to use,
134 .I curses
135 may substitute a
136 different video attribute for it.
137 .B \%termattrs
138 and
139 .B \%term_attrs
140 return a logical \*(``or\*('' of all video attributes supported by the
141 terminal using
142 .B A_
143 and
144 .B WA_
145 constants respectively.
146 This information is useful when a
147 .I curses
148 program
149 needs complete control over the appearance of the screen.
150 .SS termname
151 .B \%termname
152 returns the terminal name used by \fBsetupterm\fP(3NCURSES).
153 .SH RETURN VALUE
154 .B \%longname
155 and
156 .B \%termname
157 return
158 .I NULL
159 on error.
160 .PP
161 Functions that return an integer return
162 .B ERR
163 upon failure and
164 .B OK
165 upon success.
166 .SH NOTES
167 .BR \%erasewchar ","
168 .BR \%killwchar ","
169 and
170 .B \%term_attrs
171 are part of
172 .IR \%ncurses "'s"
173 wide-character API,
174 and are not available in its non-wide-character configuration.
175 .PP
176 .B \%termattrs
177 may be implemented as a macro.
178 .SH PORTABILITY
179 X/Open Curses Issue\ 4 describes these functions.
180 .PP
181 SVr4 describes a successful return value only as
182 \*(``an integer value other than
183 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 535
184 .PP
185 Most versions of
186 .I curses
187 truncate the string returned by
188 .I \%termname
189 to 14 characters.
190 .SH HISTORY
191 4BSD (1980)
192 introduced
193 .IR \%longname "."
194 .PP
195 SVr2 (1984)
196 added
197 .IR \%baudrate ","
198 .IR \%erasechar ","
199 .IR \%killchar ","
200 .IR \%has_ic ","
201 and
202 .IR \%has_il "."
203 .PP
204 SVr3 (1987)
205 supplied
206 .IR \%termname "."
207 Later that year,
208 SVr3.1 brought
209 .IR \%termattrs "."
210 .PP
211 X/Open Curses Issue\ 4 (1995)
212 specified
213 .IR \%erasewchar ","
214 .IR \%killwchar ","
215 and
216 .IR \%term_attrs "."
217 .SH SEE ALSO
218 \fB\%ncurses\fP(3NCURSES),
219 \fB\%initscr\fP(3NCURSES),
220 \fB\%outopts\fP(3NCURSES)