Debian Codegraph @

doc/html/man/curs_addch.3x.html

raw
1 <!--
2 * t
3 ****************************************************************************
4 * Copyright 2018-2024,2025 Thomas E. Dickey *
5 * Copyright 1998-2015,2017 Free Software Foundation, Inc. *
6 * *
7 * Permission is hereby granted, free of charge, to any person obtaining a *
8 * copy of this software and associated documentation files (the *
9 * "Software"), to deal in the Software without restriction, including *
10 * without limitation the rights to use, copy, modify, merge, publish, *
11 * distribute, distribute with modifications, sublicense, and/or sell *
12 * copies of the Software, and to permit persons to whom the Software is *
13 * furnished to do so, subject to the following conditions: *
14 * *
15 * The above copyright notice and this permission notice shall be included *
16 * in all copies or substantial portions of the Software. *
17 * *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * *
26 * Except as contained in this notice, the name(s) of the above copyright *
27 * holders shall not be used in advertising or otherwise to promote the *
28 * sale, use or other dealings in this Software without prior written *
29 * authorization. *
30 ****************************************************************************
31 * @Id: curs_addch.3x,v 1.144 2025/11/12 01:04:12 tom Exp @
32 -->
33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <HTML>
35 <HEAD>
36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
38 <TITLE>curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</TITLE>
39 <link rel="author" href="mailto:[email protected]">
40
41 </HEAD>
42 <BODY>
43 <H1 class="no-header">curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</H1>
44 <PRE>
45 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
46
47
48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
49 <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a <EM>curses</EM>
50 character to a window and advance the cursor
51
52
53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
54 <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
55
56 <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
57 <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
58 <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
59 <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
60
61 <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
62 <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
63
64 <EM>/*</EM> <EM>(integer)</EM> <EM>constants</EM> <EM>*/</EM>
65 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BLOCK;</STRONG>
66 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BOARD;</STRONG>
67 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BTEE;</STRONG>
68 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BULLET;</STRONG>
69 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_CKBOARD;</STRONG>
70 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DARROW;</STRONG>
71 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DEGREE;</STRONG>
72 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DIAMOND;</STRONG>
73 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_HLINE;</STRONG>
74 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LANTERN;</STRONG>
75 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LARROW;</STRONG>
76 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LLCORNER;</STRONG>
77 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LRCORNER;</STRONG>
78 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LTEE;</STRONG>
79 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLMINUS;</STRONG>
80 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLUS;</STRONG>
81 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RARROW;</STRONG>
82 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RTEE;</STRONG>
83 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S1;</STRONG>
84 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S9;</STRONG>
85 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_TTEE;</STRONG>
86 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_UARROW;</STRONG>
87 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_ULCORNER;</STRONG>
88 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_URCORNER;</STRONG>
89 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_VLINE;</STRONG>
90 <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
91 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_GEQUAL;</STRONG>
92 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LEQUAL;</STRONG>
93 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_NEQUAL;</STRONG>
94 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PI;</STRONG>
95 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S3;</STRONG>
96 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S7;</STRONG>
97 /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_STERLING;</STRONG>
98
99
100 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
101
102 </PRE><H3><a name="h3-waddch">waddch</a></H3><PRE>
103 <STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances
104 the cursor position, analogously to the standard C library's
105 <STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
106
107 Construct a <EM>curses</EM> character from a <EM>char</EM> by assignment or typecast.
108 Subsection "Video Attributes" of <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG> describes how to manipulate
109 its attributes and color pair. (A color pair selection is not honored
110 unless initialized; see <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>.)
111
112 The object or expression <EM>ch</EM> may contain attributes and/or a color pair
113 identifier. (A <EM>chtype</EM> can be copied from place to place using
114 <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) <EM>curses</EM> defines constants to aid the
115 manipulation of character attributes; see <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. A <EM>ch</EM> whose
116 character component is a space, and whose only attribute is <STRONG>A_NORMAL</STRONG>,
117 is a <EM>blank</EM> <EM>character</EM>, and therefore combines with the window's
118 background character; see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
119
120 If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
121 moves appropriately within the window.
122
123 <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
124 of a window, it does nothing.
125
126 <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the same
127 line of the window.
128
129 <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right
130 margin.
131
132 <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
133 line); these are placed at every eighth column by default.
134
135 Alter the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
136 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
137
138 If <EM>ch</EM> is any other nonprintable character, <EM>curses</EM> draws it in printable
139 form using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>. Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the
140 location of a nonprintable character does not return the character
141 itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
142
143 Adding printable characters with <STRONG>waddch</STRONG> causes it to wrap at the right
144 margin of the window:
145
146 <STRONG>o</STRONG> If the cursor is not at the bottom of the scrolling region and
147 advancement occurs at the right margin, the cursor automatically
148 wraps to the beginning of the next line.
149
150 <STRONG>o</STRONG> If the cursor is at the bottom of the scrolling region when
151 advancement occurs at the right margin, and <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled
152 for <EM>win</EM>, the scrolling region scrolls up one line and the cursor
153 wraps as above. Otherwise, advancement and scrolling do not occur,
154 and <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG>.
155
156 A window's margins may coincide with the screen boundaries. This may
157 be a problem when <EM>ncurses</EM> updates the screen to match the curses
158 window. When their right and bottom margins coincide, <EM>ncurses</EM> uses
159 different strategies to handle the variations of scrolling and wrapping
160 at the lower-right corner by depending on the terminal capabilities:
161
162 <STRONG>o</STRONG> If the terminal does not automatically wrap as characters are added
163 at the right margin (i.e., auto right margins), <EM>ncurses</EM> writes the
164 character directly.
165
166 <STRONG>o</STRONG> If the terminal has auto right margins, but also has capabilities
167 for turning auto margins off and on, <EM>ncurses</EM> turns the auto margin
168 feature off temporarily when writing to the lower-right corner.
169
170 <STRONG>o</STRONG> If the terminal has an insertion mode which can be turned off and
171 on, <EM>ncurses</EM> writes the character just before the lower-right
172 corner, and then inserts a character to push the update into the
173 corner.
174
175
176 </PRE><H3><a name="h3-wechochar">wechochar</a></H3><PRE>
177 <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
178 (<STRONG>w</STRONG>)<STRONG>refresh</STRONG> on <STRONG>stdscr</STRONG> or the specified window. <EM>curses</EM> interprets these
179 functions as a hint to its optimizer that only a single character cell
180 in the window is being altered between refreshes; for non-control
181 characters, a considerable performance gain may be enjoyed by employing
182 them.
183
184
185 </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
186 <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
187 to write line-drawing and other symbols to the screen. <EM>ncurses</EM> terms
188 these <EM>forms-drawing</EM> <EM>characters.</EM> <EM>curses</EM> uses the ACS default listed
189 below if the terminal type lacks the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capability; that
190 capability does not define a replacement for the character; or if the
191 terminal type and locale configuration require Unicode to access these
192 characters, but the library is unable to use Unicode. The "acsc char"
193 column corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG>
194 (<STRONG>acsc</STRONG>) string capability, and the characters in it may appear on the
195 screen if the terminal type's database entry incorrectly advertises ACS
196 support. The name "ACS" originates in the Alternate Character Set
197 feature of the DEC VT100 terminal.
198
199 <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
200 <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
201 ------------------------------------------------------------------------
202 <STRONG>ACS_BLOCK</STRONG> # 0 solid square block
203 <STRONG>ACS_BOARD</STRONG> # h board of squares
204 <STRONG>ACS_BTEE</STRONG> + v bottom tee
205 <STRONG>ACS_BULLET</STRONG> o ~ bullet
206 <STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple)
207 <STRONG>ACS_DARROW</STRONG> v . arrow pointing down
208 <STRONG>ACS_DEGREE</STRONG> ' f degree symbol
209 <STRONG>ACS_DIAMOND</STRONG> + ` diamond
210 <STRONG>ACS_GEQUAL</STRONG> &gt; &gt; greater-than-or-equal-to
211 <STRONG>ACS_HLINE</STRONG> - q horizontal line
212 <STRONG>ACS_LANTERN</STRONG> # i lantern symbol
213 <STRONG>ACS_LARROW</STRONG> &lt; , arrow pointing left
214 <STRONG>ACS_LEQUAL</STRONG> &lt; y less-than-or-equal-to
215 <STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner
216 <STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner
217 <STRONG>ACS_LTEE</STRONG> + t left tee
218 <STRONG>ACS_NEQUAL</STRONG> ! | not-equal
219 <STRONG>ACS_PI</STRONG> * { greek pi
220 <STRONG>ACS_PLMINUS</STRONG> # g plus/minus
221 <STRONG>ACS_PLUS</STRONG> + n plus
222 <STRONG>ACS_RARROW</STRONG> &gt; + arrow pointing right
223 <STRONG>ACS_RTEE</STRONG> + u right tee
224 <STRONG>ACS_S1</STRONG> - o scan line 1
225 <STRONG>ACS_S3</STRONG> - p scan line 3
226 <STRONG>ACS_S7</STRONG> - r scan line 7
227 <STRONG>ACS_S9</STRONG> _ s scan line 9
228 <STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol
229 <STRONG>ACS_TTEE</STRONG> + w top tee
230 <STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up
231 <STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner
232 <STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner
233 <STRONG>ACS_VLINE</STRONG> | x vertical line
234
235
236 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
237 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
238
239 In <EM>ncurses</EM>, these functions fail if
240
241 <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized,
242
243 <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null
244 pointer,
245
246 <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
247 been called on <EM>win</EM> (or <STRONG>stdscr</STRONG>, as applicable) when a write to its
248 bottom right location is attempted, or
249
250 <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
251 position.
252
253 The last may be due to different causes:
254
255 <STRONG>o</STRONG> conversion of a wide character to a multibyte character sequence
256 can fail, or
257
258 <STRONG>o</STRONG> at least one of the bytes resulting from wide character conversion
259 to a multibyte character sequence cannot be added to the window.
260 See section "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with
261 wide characters.
262
263 Functions prefixed with "mv" first perform cursor movement and fail if
264 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
265
266
267 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
268 <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
269
270
271 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
272 The symbols <EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>,
273 and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM> were not documented in any publicly released System V
274 and are not standard. However, many publicly available <EM>terminfo</EM>
275 entries include <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capabilities in which their key
276 characters (<STRONG>pryz{|}</STRONG>) are embedded, and a second-hand list of their
277 character descriptions has come to light, which identifies them as
278 VT100 special characters.
279
280 The DEC Special Character and Line Drawing Set (VT100) is indexed by an
281 ASCII character in the range 96 (`) to 126 (~). That index character
282 is part of the definition for the curses <STRONG>ACS_</STRONG> symbols. The VT100
283 special characters can be categorized in three groups:
284
285 <STRONG>o</STRONG> useful graphic symbols with a standard <STRONG>ACS_</STRONG> symbol, (e.g., the
286 line-drawing symbols),
287
288 <STRONG>o</STRONG> possibly useful characters (these non-standard symbols),
289
290 <STRONG>o</STRONG> representations of control characters (e.g., newline and vertical
291 tabulation).
292
293 A few <STRONG>ACS_</STRONG> symbols do not fit into DEC's VT100 scheme. The AT&amp;T
294 Teletype 5410v1 arrow symbols and <STRONG>ACS_BLOCK</STRONG> use indices outside the
295 range 96 to 126. Two of the Teletype symbols use indices in that
296 range, with different meaning versus the VT100:
297
298 <STRONG>o</STRONG> <STRONG>ACS_BOARD</STRONG> corresponds to the VT100 symbol for newline
299
300 <STRONG>o</STRONG> <STRONG>ACS_LANTERN</STRONG> corresponds to the VT100 symbol for vertical tabulation
301
302 AT&amp;T defined <STRONG>ACS_</STRONG> names for the most useful graphic symbols, as well as
303 for its own. Its header file commented:
304
305 /*
306 * Standard alternate character set. The current ACS world is
307 * evolving, so we support only a widely available subset: the
308 * line drawing characters from the VT100, plus a few from the
309 * Teletype 5410v1. Eventually there may be support of more
310 * sophisticated ACS line drawing, such as that in the Teletype
311 * 5410, the HP line drawing set, and the like. There may be
312 * support for some non line oriented characters as well.
313 *
314 * Line drawing ACS names are of the form ACS_trbl, where t is
315 * the top, r is the right, b is the bottom, and l is the left.
316 * t, r, b, and l might be B (blank), S (single), D (double), or
317 * T (thick). The subset defined here only uses B and S.
318 */
319
320 Although these less-useful graphic symbols were not given names, they
321 were used in <EM>terminfo</EM> entries. The <EM>ncurses</EM> developers invented ACS-
322 prefixed names for them.
323
324
325 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
326 Applications employing <EM>ncurses</EM> extensions should condition their use on
327 the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
328
329 X/Open Curses Issue 4 describes these functions. It specifies no error
330 conditions for them.
331
332 SVr4 describes a successful return value only as "an integer value
333 other than <EM>ERR</EM>".
334
335 The defaults specified for forms-drawing characters apply in the POSIX
336 locale.
337
338
339 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
340 X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <EM>char</EM> constants.
341 Some implementations are problematic.
342
343 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants;
344 others define them as elements of an array.
345
346 SVr4 used an array, <EM>acs</EM><STRONG>_</STRONG><EM>map</EM>, as does <EM>ncurses</EM>. NetBSD <EM>curses</EM> also
347 uses an array, actually named <STRONG>_</STRONG><EM>acs</EM><STRONG>_</STRONG><EM>char</EM>, with a "#define" for
348 compatibility.
349
350 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous
351 <EM>WACS</EM><STRONG>_</STRONG> symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters (see
352 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
353 others that are not used for line drawing.
354
355 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
356 the <EM>ACS</EM><STRONG>_</STRONG><EM>LANTERN</EM> symbol, equating its "VT100+ Character" to "I"
357 (capital I), while the header files for SVr4 <EM>curses</EM> and other
358 implementations use "i" (small i).
359
360 None of the terminal descriptions on Unix platforms use uppercase
361 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
362 apparently based on the X/Open documentation around 1995). On the
363 other hand, its <STRONG>gs6300</STRONG> (AT&amp;T PC6300 with EMOTS Terminal Emulator)
364 description uses lowercase i.
365
366 The <EM>displayed</EM> values of <EM>ACS</EM><STRONG>_</STRONG> constants depend on
367
368 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI -- for example, wide-character versus non-wide-
369 character configurations (the former is capable of displaying
370 Unicode while the latter is not), and
371
372 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
373
374 In certain cases, the terminal is unable to display forms-drawing
375 characters <EM>except</EM> by using UTF-8; see the discussion of the
376 <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
377
378
379 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
380 X/Open Curses assumes that the parameter passed to <EM>waddch</EM> contains a
381 single character. That character may have been more than eight bits
382 wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the
383 width of a non-wide character code unspecified. The standard further
384 does not specify the internal structure of a <EM>chtype</EM>, though the use of
385 bitwise operators to combine the character code with attributes and a
386 color pair identifier into a <EM>chtype</EM> for passage to <EM>waddch</EM> is common. A
387 portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to
388 manipulate a <EM>chtype</EM>.
389
390 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows
391 a multibyte character sequence to be passed via a succession of calls
392 to <EM>waddch</EM>. Other implementations do not; a <EM>waddch</EM> call transmits
393 exactly one character, which may be rendered in one or more screen
394 locations depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>).
395 Depending on the locale, <EM>ncurses</EM> inspects the byte passed in each
396 <EM>waddch</EM> call and checks whether the latest call continues a multibyte
397 character. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
398 character and advances the cursor. If the calling application
399 interrupts the succession of bytes in a multibyte character sequence by
400 changing the current location -- for example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> -- <EM>ncurses</EM>
401 discards the incomplete character.
402
403 For portability to other implementations, do not rely upon the
404 foregoing behavior. Check whether a character can be represented as a
405 single byte in the current locale.
406
407 <STRONG>o</STRONG> If it can, call either <EM>waddch</EM> or <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>.
408
409 <STRONG>o</STRONG> If it cannot, use only <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>.
410
411
412 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
413 4BSD (1980) introduced <EM>waddch</EM> and its variants.
414
415 SVr3 (1987) added the <EM>echochar</EM> and <EM>wechochar</EM> functions and most of the
416 <EM>ACS</EM><STRONG>_</STRONG> constants, except for <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>,
417 <EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM>.
418
419 <EM>ncurses</EM> 1.9.6 (1995) furnished the remaining <EM>ACS</EM><STRONG>_</STRONG> constants.
420
421
422 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
423 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
424 in its wide-character configuration (<EM>ncursesw</EM>).
425
426 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,
427 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>,
428 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG>
429
430 ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
431 </PRE>
432 <div class="nav">
433 <ul>
434 <li><a href="#h2-NAME">NAME</a></li>
435 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
436 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
437 <ul>
438 <li><a href="#h3-waddch">waddch</a></li>
439 <li><a href="#h3-wechochar">wechochar</a></li>
440 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
441 </ul>
442 </li>
443 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
444 <li><a href="#h2-NOTES">NOTES</a></li>
445 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
446 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
447 <ul>
448 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
449 <li><a href="#h3-Character-Set">Character Set</a></li>
450 </ul>
451 </li>
452 <li><a href="#h2-HISTORY">HISTORY</a></li>
453 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
454 </ul>
455 </div>
456 </BODY>
457 </HTML>