Debian Codegraph @

upstream/mageia-cauldron/man3/curs_addch.3x

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
4 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
5 .\" *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
13 .\" *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
16 .\" *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
28 .\" authorization. *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: curs_addch.3x,v 1.139 2025/07/05 12:43:18 tom Exp $
32 .TH curs_addch 3X 2025-07-05 "ncurses 6.5" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .ds ' \(aq
37 .ds ^ \(ha
38 .ds ~ \(ti
39 .\}
40 .el \{\
41 .ie t .ds `` ``
42 .el .ds `` ""
43 .ie t .ds '' ''
44 .el .ds '' ""
45 .ds ' '
46 .ds ^ ^
47 .ds ~ ~
48 .\}
49 .
50 .de bP
51 .ie n .IP \(bu 4
52 .el .IP \(bu 2
53 ..
54 .SH NAME
55 \fB\%addch\fP,
56 \fB\%waddch\fP,
57 \fB\%mvaddch\fP,
58 \fB\%mvwaddch\fP,
59 \fB\%echochar\fP,
60 \fB\%wechochar\fP \-
61 add a \fIcurses\fP character to a window and advance the cursor
62 .SH SYNOPSIS
63 .nf
64 \fB#include <curses.h>
65 .PP
66 \fBint addch(const chtype \fIch\fP);
67 \fBint waddch(WINDOW * \fIwin\fP, const chtype \fIch\fP);
68 \fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
69 \fBint mvwaddch(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
70 .PP
71 \fBint echochar(const chtype \fIch\fP);
72 \fBint wechochar(WINDOW * \fIwin\fP, const chtype \fIch\fP);
73 .PP
74 \fI/* (integer) constants */\fP
75 /*\fI .\|.\|. */ \fBACS_BLOCK;\fR
76 /*\fI .\|.\|. */ \fBACS_BOARD;\fR
77 /*\fI .\|.\|. */ \fBACS_BTEE;\fR
78 /*\fI .\|.\|. */ \fBACS_BULLET;\fR
79 /*\fI .\|.\|. */ \fBACS_CKBOARD;\fR
80 /*\fI .\|.\|. */ \fBACS_DARROW;\fR
81 /*\fI .\|.\|. */ \fBACS_DEGREE;\fR
82 /*\fI .\|.\|. */ \fBACS_DIAMOND;\fR
83 /*\fI .\|.\|. */ \fBACS_HLINE;\fR
84 /*\fI .\|.\|. */ \fBACS_LANTERN;\fR
85 /*\fI .\|.\|. */ \fBACS_LARROW;\fR
86 /*\fI .\|.\|. */ \fBACS_LLCORNER;\fR
87 /*\fI .\|.\|. */ \fBACS_LRCORNER;\fR
88 /*\fI .\|.\|. */ \fBACS_LTEE;\fR
89 /*\fI .\|.\|. */ \fBACS_PLMINUS;\fR
90 /*\fI .\|.\|. */ \fBACS_PLUS;\fR
91 /*\fI .\|.\|. */ \fBACS_RARROW;\fR
92 /*\fI .\|.\|. */ \fBACS_RTEE;\fR
93 /*\fI .\|.\|. */ \fBACS_S1;\fR
94 /*\fI .\|.\|. */ \fBACS_S9;\fR
95 /*\fI .\|.\|. */ \fBACS_TTEE;\fR
96 /*\fI .\|.\|. */ \fBACS_UARROW;\fR
97 /*\fI .\|.\|. */ \fBACS_ULCORNER;\fR
98 /*\fI .\|.\|. */ \fBACS_URCORNER;\fR
99 /*\fI .\|.\|. */ \fBACS_VLINE;\fR
100 \fI/* extensions */\fP
101 /*\fI .\|.\|. */ \fBACS_GEQUAL;\fR
102 /*\fI .\|.\|. */ \fBACS_LEQUAL;\fR
103 /*\fI .\|.\|. */ \fBACS_NEQUAL;\fR
104 /*\fI .\|.\|. */ \fBACS_PI;\fR
105 /*\fI .\|.\|. */ \fBACS_S3;\fR
106 /*\fI .\|.\|. */ \fBACS_S7;\fR
107 /*\fI .\|.\|. */ \fBACS_STERLING;\fR
108 .fi
109 .SH DESCRIPTION
110 .SS waddch
111 .B \%waddch
112 writes the
113 .I curses
114 character
115 .I ch
116 to the window
117 .IR win ","
118 then advances the cursor position,
119 analogously to the standard C library's \fI\%putchar\fP(3).
120 \fB\%ncurses\fP(3X) describes the variants of this function.
121 .PP
122 Construct a
123 .I curses
124 character
125 from a
126 .I char
127 by assignment or typecast.
128 Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3X) describes
129 how to manipulate its attributes and color pair.
130 (A color pair selection is not honored unless initialized;
131 see \fB\%start_color\fP(3X).)
132 .PP
133 The object or expression
134 .I ch
135 may contain attributes and/or a color pair identifier.
136 (A
137 .I \%chtype
138 can be copied from place to place using \fB\%winch\fP(3X) and
139 .BR \%waddch .)
140 See \fB\%curs_attr\fP(3X) for values of predefined constants that can be
141 usefully \*(``or\*(''ed with characters.
142 A
143 .I ch
144 whose character component is a space,
145 and whose only attribute is
146 .BR \%A_NORMAL ,
147 is a
148 .IR "blank character" ","
149 and therefore combines with the window's background character;
150 see \fB\%curs_bkgd\fP(3X).
151 .PP
152 If
153 .I ch
154 is a
155 backspace,
156 carriage return,
157 line feed,
158 or
159 tab,
160 the cursor moves appropriately within the window.
161 .bP
162 Backspace moves the cursor one character left;
163 at the left margin of a window,
164 it does nothing.
165 .bP
166 Carriage return moves the cursor to the left margin on the same line of
167 the window.
168 .bP
169 Line feed does a \fB\%clrtoeol\fP(3X),
170 then advances as if from the right margin.
171 .bP
172 Tab advances the cursor to the next tab stop
173 (possibly on the next line);
174 these are placed at every eighth column by default.
175 .IP
176 Alter the tab interval with the
177 .B \%TABSIZE
178 extension;
179 see \fB\%curs_variables\fP(3X).
180 .PP
181 If
182 .I ch
183 is any other nonprintable character,
184 .I curses
185 draws it in printable form using the same convention as
186 \fB\%unctrl\fP(3X).
187 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
188 does not return the character itself,
189 but its \fB\%unctrl\fP(3X) representation.
190 .PP
191 Adding printable characters with \fB\%waddch\fP
192 causes it to wrap at the right margin of the window:
193 .bP
194 If the cursor is not at the bottom of the scrolling region
195 and advancement occurs at the right margin,
196 the cursor automatically wraps to the beginning of the next line.
197 .bP
198 If the cursor is at the bottom of the scrolling region
199 when advancement occurs at the right margin,
200 and \fB\%scrollok\fP(3X) is enabled for
201 .IR win ,
202 the scrolling region scrolls up one line
203 and the cursor wraps as above.
204 Otherwise,
205 advancement and scrolling do not occur,
206 and
207 .B \%waddch
208 returns
209 .BR ERR "."
210 .PP
211 A window's margins may coincide with the screen boundaries.
212 This may be a problem when
213 .I \%ncurses
214 updates the screen to match the curses window.
215 When their right and bottom margins coincide,
216 .I \%ncurses
217 uses different strategies to handle the variations of scrolling and wrapping
218 at the lower-right corner
219 by depending on the terminal capabilities:
220 .bP
221 If the terminal does not automatically wrap as characters
222 are added at the right margin
223 (i.e., auto right margins),
224 .I \%ncurses
225 writes the character directly.
226 .bP
227 If the terminal has auto right margins,
228 but also has capabilities for turning auto margins off and on,
229 .I \%ncurses
230 turns the auto margin feature off temporarily
231 when writing to the lower-right corner.
232 .bP
233 If the terminal has an insertion mode which can be turned off and on,
234 .I \%ncurses
235 writes the character just before the lower-right corner,
236 and then inserts a character to push the update into the corner.
237 .SS wechochar
238 .B \%echochar
239 and
240 .B \%wechochar
241 are equivalent to calling
242 .RB \%( w ) addch
243 followed by
244 .RB \%( w ) refresh
245 on
246 .B \%stdscr
247 or the specified window.
248 .I curses
249 interprets these functions as a hint to its optimizer
250 that only a single character cell in the window
251 is being altered between refreshes;
252 for non-control characters,
253 a considerable performance gain may be enjoyed by employing them.
254 .\" TODO: Combine the following with the "Line Drawing" subsection of
255 .\" terminfo(5) and replace this with a cross reference there.
256 .SS "Forms-Drawing Characters"
257 .I curses
258 defines macros starting with
259 .B \%ACS_
260 that can be used with
261 .B \%waddch
262 to write line-drawing and other symbols to the screen.
263 .I \%ncurses
264 terms these
265 .I "forms-drawing characters."
266 .I curses
267 uses the ACS default listed below if the terminal type lacks the
268 .B \%acs_chars
269 .RB \%( acsc )
270 capability;
271 that capability does not define a replacement for the character;
272 or if the terminal type and locale configuration
273 require Unicode to access these characters,
274 but the library is unable to use Unicode.
275 The \*(``acsc char\*('' column corresponds to how the characters are
276 specified in the
277 .B \%acs_chars
278 .RB \%( acsc )
279 string capability,
280 and the characters in it may appear on the screen if the terminal type's
281 database entry incorrectly advertises ACS support.
282 The name \*(``ACS\*('' originates in the Alternate Character Set feature
283 of the DEC VT100 terminal.
284 .PP
285 .ie t .ne 4v
286 .el .ne 5v
287 .TS
288 Lb Lb Lb Lb
289 Lb Lb Lb Lb
290 Lb L L Lx.
291 \& ACS acsc \&
292 Symbol Default char Glyph Name
293 _
294 ACS_BLOCK # 0 solid square block
295 ACS_BOARD # h board of squares
296 ACS_BTEE + v bottom tee
297 ACS_BULLET o \*~ bullet
298 ACS_CKBOARD : a checker board (stipple)
299 ACS_DARROW v . arrow pointing down
300 ACS_DEGREE \*' f degree symbol
301 ACS_DIAMOND + \(ga diamond
302 ACS_GEQUAL > > greater-than-or-equal-to
303 ACS_HLINE \- q horizontal line
304 ACS_LANTERN # i lantern symbol
305 ACS_LARROW < , arrow pointing left
306 ACS_LEQUAL < y less-than-or-equal-to
307 ACS_LLCORNER + m lower left-hand corner
308 ACS_LRCORNER + j lower right-hand corner
309 ACS_LTEE + t left tee
310 ACS_NEQUAL ! | not-equal
311 ACS_PI * { greek pi
312 ACS_PLMINUS # g plus/minus
313 ACS_PLUS + n plus
314 ACS_RARROW > + arrow pointing right
315 ACS_RTEE + u right tee
316 ACS_S1 \- o scan line 1
317 ACS_S3 \- p scan line 3
318 ACS_S7 \- r scan line 7
319 ACS_S9 \&_ s scan line 9
320 ACS_STERLING f } pound-sterling symbol
321 ACS_TTEE + w top tee
322 ACS_UARROW \*^ \- arrow pointing up
323 ACS_ULCORNER + l upper left-hand corner
324 ACS_URCORNER + k upper right-hand corner
325 ACS_VLINE | x vertical line
326 .TE
327 .SH RETURN VALUE
328 These functions return
329 .B OK
330 on success and
331 .B ERR
332 on failure.
333 .PP
334 In
335 .IR \%ncurses ,
336 these functions fail if
337 .bP
338 the
339 .I curses
340 screen has not been initialized,
341 .bP
342 (for functions taking a
343 .I \%WINDOW
344 pointer argument)
345 .I win
346 is a null pointer,
347 .bP
348 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
349 not been called on
350 .I win
351 (or
352 .BR \%stdscr ","
353 as applicable)
354 when a write to its bottom right location is attempted,
355 or
356 .bP
357 it is not possible to add a complete character at the cursor position.
358 .PP
359 The last may be due to different causes:
360 .bP
361 conversion of a wide character to a multibyte character sequence can
362 fail,
363 or
364 .bP
365 at least one of the bytes resulting from wide character conversion to a
366 multibyte character sequence cannot be added to the window.
367 See section \*(``PORTABILITY\*('' below regarding the use of
368 .B \%waddch
369 with wide characters.
370 .PP
371 Functions prefixed with \*(``mv\*('' first perform cursor movement and
372 fail if the position
373 .RI ( y ,
374 .IR x )
375 is outside the window boundaries.
376 .SH NOTES
377 .BR \%addch ","
378 .BR \%mvaddch ","
379 .BR \%mvwaddch ","
380 and
381 .B \%echochar
382 may be implemented as macros.
383 .SH EXTENSIONS
384 The symbols
385 .IR \%ACS_S3 ","
386 .IR \%ACS_S7 ","
387 .IR \%ACS_LEQUAL ","
388 .IR \%ACS_GEQUAL ","
389 .IR \%ACS_PI ","
390 .IR \%ACS_NEQUAL ","
391 and
392 .I \%ACS_STERLING
393 were not documented in any publicly released System\ V
394 .\" And did not exist yet as late as SVr4.
395 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
396 .\" sysvr4/svr4/lib/xlibcurses/screen/curses.ed
397 and are not standard.
398 However,
399 many publicly available
400 .I \%term\%info
401 entries include
402 .B \%acs_chars
403 .RB \%( acsc )
404 capabilities in which their key characters
405 .RB ( pryz{|} )
406 are embedded,
407 and a second-hand list of their character descriptions has come to light,
408 which identifies them as VT100 special characters.
409 .PP
410 The DEC Special Character and Line Drawing Set (VT100) is indexed by
411 an ASCII character in the range 96 (`) to 126 (~).
412 That index character is part of the definition for the curses
413 .B \%ACS_
414 symbols.
415 The VT100 special characters can be categorized in three groups:
416 .bP
417 useful graphic symbols with a standard
418 .B \%ACS_
419 symbol,
420 (e.g., the line-drawing symbols),
421 .bP
422 possibly useful characters (these non-standard symbols),
423 .bP
424 representations of control characters (e.g., newline and vertical tabulation).
425 .PP
426 A few
427 .B \%ACS_
428 symbols do not fit into DEC's VT100 scheme.
429 The AT&T Teletype 5410v1 arrow symbols and
430 .B \%ACS_BLOCK
431 use indices outside the range 96 to 126.
432 Two of the Teletype symbols use indices in that range,
433 with different meaning versus the VT100:
434 .bP
435 .B \%ACS_BOARD
436 corresponds to the VT100 symbol for newline
437 .bP
438 .B \%ACS_LANTERN
439 corresponds to the VT100 symbol for vertical tabulation
440 .PP
441 AT&T defined
442 .B \%ACS_
443 names for the most useful graphic symbols,
444 as well as for its own.
445 Its header file commented:
446 .sp
447 .EX
448 /*
449 * Standard alternate character set. The current ACS world is evolving,
450 * so we support only a widely available subset: the line drawing characters
451 * from the VT100, plus a few from the Teletype 5410v1. Eventually there
452 * may be support of more sophisticated ACS line drawing, such as that
453 * in the Teletype 5410, the HP line drawing set, and the like. There may
454 * be support for some non line oriented characters as well.
455 *
456 * Line drawing ACS names are of the form ACS_trbl, where t is the top, r
457 * is the right, b is the bottom, and l is the left. t, r, b, and l might
458 * be B (blank), S (single), D (double), or T (thick). The subset defined
459 * here only uses B and S.
460 */
461 .EE
462 .PP
463 Although these less-useful graphic symbols were not given names,
464 they were used in
465 .I \%terminfo
466 entries.
467 The
468 .I \%ncurses
469 developers invented ACS-prefixed names for them.
470 .\" in v1_9_5_950928_e227
471 .SH PORTABILITY
472 Applications employing
473 .I \%ncurses
474 extensions should condition their use on the visibility of the
475 .B \%NCURSES_VERSION
476 preprocessor macro.
477 .PP
478 X/Open Curses Issue\ 4 describes these functions.
479 It specifies no error conditions for them.
480 .PP
481 SVr4 describes a successful return value only as
482 \*(``an integer value other than
483 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 472
484 .PP
485 The defaults specified for forms-drawing characters apply in the POSIX
486 locale.
487 .SS "ACS Symbols"
488 X/Open Curses states that the
489 .I \%ACS_
490 definitions are
491 .I char
492 constants.
493 Some implementations are problematic.
494 .bP
495 Solaris
496 .IR curses ,
497 for example,
498 defines the ACS symbols as constants;
499 others define them as elements of an array.
500 .IP
501 SVr4 used an array,
502 .IR \%acs_map ,
503 as does
504 .IR \%ncurses "."
505 NetBSD
506 .I curses
507 also uses an array,
508 actually named
509 .IR \%_acs_char ,
510 with a \%\*(``#define\*('' for compatibility.
511 .bP
512 HP-UX
513 .I curses
514 equates some of the
515 .I \%ACS_
516 symbols to the analogous
517 .I \%WACS_
518 symbols as if the
519 .I \%ACS_
520 symbols were wide characters
521 (see \fB\%curs_add_wch\fP(3X)).
522 The misdefined symbols are the arrows and others that are not used for
523 line drawing.
524 .bP
525 X/Open Curses
526 (Issues\ 2 through 7)
527 has a typographical error
528 for the
529 .I \%ACS_LANTERN
530 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
531 (capital I),
532 while the header files for SVr4
533 .I curses
534 and other implementations use \*(``i\*(''
535 (small i).
536 .IP
537 None of the terminal descriptions on Unix platforms use uppercase I,
538 except for Solaris
539 (in its
540 .I \%term\%info
541 entry for \fI\%screen\fP(1),
542 apparently based on the X/Open documentation around 1995).
543 On the other hand,
544 its
545 .B \%gs6300
546 (AT&T PC6300 with EMOTS Terminal Emulator)
547 description uses lowercase i.
548 .PP
549 The
550 .I displayed
551 values of
552 .I \%ACS_
553 constants depend on
554 .bP
555 the
556 .I \%ncurses
557 ABI \(em
558 for example,
559 wide-character versus non-wide-character configurations
560 (the former is capable of displaying Unicode while the latter is not),
561 and
562 .bP
563 whether the locale uses UTF-8 encoding.
564 .PP
565 In certain cases,
566 the terminal is unable to display forms-drawing characters
567 .I except
568 by using UTF-8;
569 see the discussion of the
570 .I \%NCURSES_NO_UTF8_ACS
571 environment variable in \fB\%ncurses\fP(3X).
572 .SS "Character Set"
573 X/Open Curses assumes that the parameter passed to
574 .I \%waddch
575 contains a single character.
576 That character may have been more than eight bits wide in an SVr3 or
577 SVr4 implementation,
578 but X/Open Curses leaves the width of a non-wide character code
579 unspecified.
580 The standard further does not specify the internal structure of a
581 .IR chtype ","
582 though the use of bit operations to combine the character code with
583 attributes and a color pair identifier into a
584 .I \%chtype
585 for passage to
586 .I \%waddch
587 is common.
588 A portable application uses only the macros discussed in
589 \fB\%curs_attr\fP(3X) to manipulate a
590 .IR \%chtype "."
591 .PP
592 In
593 .IR \%ncurses ,
594 .I \%chtype
595 holds an eight-bit character,
596 but the library allows a multibyte character sequence to be passed via a
597 succession of calls to
598 .IR \%waddch "."
599 Other implementations do not;
600 a
601 .I \%waddch
602 call transmits exactly one character,
603 which may be rendered in one or more screen locations depending on
604 whether it is printable
605 (see \fB\%unctrl\fP(3X)).
606 Depending on the locale,
607 .I \%ncurses
608 inspects the byte passed in each
609 .I \%waddch
610 call and checks whether the latest call continues a multibyte character.
611 When a character is
612 .IR complete ","
613 .I \%ncurses
614 displays the character and advances the cursor.
615 If the calling application interrupts the succession of bytes in
616 a multibyte character sequence by changing the current location \(em
617 for example,
618 with \fB\%wmove\fP(3X) \(em
619 .I \%ncurses
620 discards the incomplete character.
621 .PP
622 For portability to other implementations,
623 do not rely upon the foregoing behavior.
624 Check whether a character can be represented as a single byte in the
625 current locale.
626 .bP
627 If it can,
628 call either
629 .I \%waddch
630 or
631 .IR \%wadd_wch "."
632 .bP
633 If it cannot,
634 use only
635 .IR \%wadd_wch "."
636 .SH HISTORY
637 4BSD (1980)
638 introduced
639 .I \%waddch
640 and its variants.
641 .PP
642 SVr3 (1987)
643 added the
644 .I \%echochar
645 and
646 .I \%wechochar
647 functions and most of the
648 .I ACS_
649 constants,
650 except for
651 .IR \%ACS_GEQUAL ","
652 .IR \%ACS_LEQUAL ","
653 .IR \%ACS_NEQUAL ","
654 .IR \%ACS_PI ","
655 .IR \%ACS_S3 ","
656 .IR \%ACS_S7 ","
657 and
658 .IR \%ACS_STERLING "."
659 .PP
660 .I \%ncurses
661 1.9.6 (1995)
662 furnished the remaining
663 .I ACS_
664 constants.
665 .SH SEE ALSO
666 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
667 .I \%ncurses
668 library in its wide-character configuration
669 .RI \%( ncursesw ).
670 .PP
671 \fB\%curses\fP(3X),
672 \fB\%curs_addchstr\fP(3X),
673 \fB\%curs_addstr\fP(3X),
674 \fB\%curs_attr\fP(3X),
675 \fB\%curs_bkgd\fP(3X),
676 \fB\%curs_clear\fP(3X),
677 \fB\%curs_inch\fP(3X),
678 \fB\%curs_outopts\fP(3X),
679 \fB\%curs_refresh\fP(3X),
680 \fB\%curs_variables\fP(3X),
681 \fB\%putchar\fP(3)