Debian Codegraph @

upstream/debian-trixie/man3/addch.3ncurses

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.122 2025/02/01 23:54:03 tom Exp $
32 .TH addch 3NCURSES 2025-02-01 "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(3NCURSES) 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.
128 Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3NCURSES) 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(3NCURSES).)
132 .PP
133 If advancement occurs at the right margin,
134 .bP
135 the cursor automatically wraps to the beginning of the next line,
136 then,
137 .bP
138 if it was at the bottom of the scrolling region,
139 and if \fB\%scrollok\fP(3NCURSES) is enabled for
140 .IR win ,
141 the scrolling region scrolls up one line.
142 .PP
143 If
144 .I ch
145 is a
146 backspace,
147 carriage return,
148 line feed,
149 or
150 tab,
151 the cursor moves appropriately within the window.
152 .bP
153 Backspace moves the cursor one character left;
154 at the left margin of a window,
155 it does nothing.
156 .bP
157 Carriage return moves the cursor to the left margin on the same line of
158 the window.
159 .bP
160 Line feed does a \fB\%clrtoeol\fP(3NCURSES),
161 then advances as if from the right margin.
162 .bP
163 Tab advances the cursor to the next tab stop
164 (possibly on the next line);
165 these are placed at every eighth column by default.
166 Alter the tab interval with the
167 .B \%TABSIZE
168 extension;
169 see \fB\%curses_variables\fP(3NCURSES).
170 .PP
171 If
172 .I ch
173 is any other nonprintable character,
174 it is drawn in printable form using the same convention as
175 \fB\%unctrl\fP(3NCURSES).
176 Calling \fB\%winch\fP(3NCURSES) on the location of a nonprintable character
177 does not return the character itself,
178 but its \fB\%unctrl\fP(3NCURSES) representation.
179 .PP
180 The object or expression
181 .I ch
182 may contain attributes and/or a color pair identifier.
183 (A
184 .I \%chtype
185 can be copied from place to place using \fB\%winch\fP(3NCURSES) and
186 .BR \%waddch .)
187 See \fB\%attr\fP(3NCURSES) for values of predefined constants that can be
188 usefully \*(``or\*(''ed with characters.
189 A
190 .I ch
191 whose character component is a space,
192 and whose only attribute is
193 .BR \%A_NORMAL ,
194 is a
195 .IR "blank character" ","
196 and therefore combines with the background character;
197 see \fB\%bkgd\fP(3NCURSES).
198 .SS wechochar
199 .B \%echochar
200 and
201 .B \%wechochar
202 are equivalent to calling
203 .RB \%( w ) addch
204 followed by
205 .RB \%( w ) refresh
206 on
207 .B \%stdscr
208 or the specified window.
209 .I curses
210 interprets these functions as a hint to its optimizer
211 that only a single character cell in the window
212 is being altered between refreshes;
213 for non-control characters,
214 a considerable performance gain may be enjoyed by employing them.
215 .\" TODO: Combine the following with the "Line Drawing" subsection of
216 .\" terminfo(5) and replace this with a cross reference there.
217 .SS "Forms-Drawing Characters"
218 .I curses
219 defines macros starting with
220 .B \%ACS_
221 that can be used with
222 .B \%waddch
223 to write line-drawing and other symbols to the screen.
224 .I \%ncurses
225 terms these
226 .I "forms-drawing characters."
227 The ACS default listed below is used if the
228 .B \%acs_chars
229 .RB \%( acsc )
230 .I \%term\%info
231 capability does not define a terminal-specific replacement for it,
232 or if the terminal and locale configuration requires Unicode to access
233 these characters but the library is unable to use Unicode.
234 The \*(``acsc char\*('' column corresponds to how the characters are
235 specified in the
236 .B \%acs_chars
237 .RB \%( acsc )
238 string capability,
239 and the characters in it may appear on the screen if the terminal type's
240 database entry incorrectly advertises ACS support.
241 The name \*(``ACS\*('' originates in the Alternate Character Set feature
242 of the DEC VT100 terminal.
243 .PP
244 .ie t .ne 4v
245 .el .ne 5v
246 .TS
247 Lb Lb Lb Lb
248 Lb Lb Lb Lb
249 Lb L L Lx.
250 \& ACS acsc \&
251 Symbol Default char Glyph Name
252 _
253 ACS_BLOCK # 0 solid square block
254 ACS_BOARD # h board of squares
255 ACS_BTEE + v bottom tee
256 ACS_BULLET o \*~ bullet
257 ACS_CKBOARD : a checker board (stipple)
258 ACS_DARROW v . arrow pointing down
259 ACS_DEGREE \*' f degree symbol
260 ACS_DIAMOND + \(ga diamond
261 ACS_GEQUAL > > greater-than-or-equal-to
262 ACS_HLINE \- q horizontal line
263 ACS_LANTERN # i lantern symbol
264 ACS_LARROW < , arrow pointing left
265 ACS_LEQUAL < y less-than-or-equal-to
266 ACS_LLCORNER + m lower left-hand corner
267 ACS_LRCORNER + j lower right-hand corner
268 ACS_LTEE + t left tee
269 ACS_NEQUAL ! | not-equal
270 ACS_PI * { greek pi
271 ACS_PLMINUS # g plus/minus
272 ACS_PLUS + n plus
273 ACS_RARROW > + arrow pointing right
274 ACS_RTEE + u right tee
275 ACS_S1 \- o scan line 1
276 ACS_S3 \- p scan line 3
277 ACS_S7 \- r scan line 7
278 ACS_S9 \&_ s scan line 9
279 ACS_STERLING f } pound-sterling symbol
280 ACS_TTEE + w top tee
281 ACS_UARROW \*^ \- arrow pointing up
282 ACS_ULCORNER + l upper left-hand corner
283 ACS_URCORNER + k upper right-hand corner
284 ACS_VLINE | x vertical line
285 .TE
286 .SH RETURN VALUE
287 These functions return
288 .B OK
289 on success and
290 .B ERR
291 on failure.
292 .PP
293 In
294 .IR \%ncurses ,
295 .B \%waddch
296 and
297 .B \%wechochar
298 return
299 .B ERR
300 if
301 .bP
302 the
303 .I curses
304 screen has not been initialized,
305 .bP
306 (for functions taking a
307 .I \%WINDOW
308 pointer argument)
309 .I win
310 is a null pointer,
311 .bP
312 wrapping to a new line is impossible because \fB\%scrollok\fP(3NCURSES) has
313 not been called on
314 .I win
315 (or
316 .BR stdscr ","
317 as applicable)
318 when a write to its bottom right location is attempted,
319 or
320 .bP
321 it is not possible to add a complete character at the cursor position.
322 .PP
323 The last may be due to different causes:
324 .bP
325 conversion of a wide character to a multibyte character sequence can
326 fail,
327 or
328 .bP
329 at least one of the bytes resulting from wide character conversion to a
330 multibyte character sequence cannot be added to the window.
331 See section \*(``PORTABILITY\*('' below regarding the use of
332 .B \%waddch
333 with wide characters.
334 .PP
335 Functions prefixed with \*(``mv\*('' first perform cursor movement and
336 fail if the position
337 .RI ( y ,
338 .IR x )
339 is outside the window boundaries.
340 .SH NOTES
341 .BR \%addch ","
342 .BR \%mvaddch ","
343 .BR \%mvwaddch ","
344 and
345 .B \%echochar
346 may be implemented as macros.
347 .SH EXTENSIONS
348 The symbols
349 .RI \%( ACS_S3 ","
350 .IR \%ACS_S7 ","
351 .IR \%ACS_LEQUAL ","
352 .IR \%ACS_GEQUAL ","
353 .IR \%ACS_PI ","
354 .IR \%ACS_NEQUAL ","
355 and
356 .IR \%ACS_STERLING ")"
357 were not documented in any publicly released System\ V
358 .\" And did not exist yet as late as SVr4.
359 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
360 .\" sysvr4/svr4/lib/xlibcurses/screen/curses.ed
361 and are not standard.
362 However,
363 many publicly available
364 .I \%term\%info
365 entries include
366 .I \%acs_chars
367 .RB \%( acsc )
368 capabilities in which their key characters
369 .RB ( pryz{|} )
370 are embedded,
371 and a second-hand list of their character descriptions has come to
372 light.
373 The
374 .I \%ncurses
375 developers invented ACS-prefixed names for them.
376 .\" in v1_9_5_950928_e227
377 .SH PORTABILITY
378 Applications employing
379 .I \%ncurses
380 extensions should condition their use on the visibility of the
381 .B \%NCURSES_VERSION
382 preprocessor macro.
383 .PP
384 X/Open Curses Issue\ 4 describes these functions.
385 It specifies no error conditions for them.
386 .PP
387 SVr4 describes a successful return value only as
388 \*(``an integer value other than
389 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 472
390 .PP
391 The defaults specified for forms-drawing characters apply in the POSIX
392 locale.
393 .SS "ACS Symbols"
394 X/Open Curses states that the
395 .I \%ACS_
396 definitions are
397 .I char
398 constants.
399 Some implementations are problematic.
400 .bP
401 Solaris
402 .IR curses ,
403 for example,
404 defines the ACS symbols as constants;
405 others define them as elements of an array.
406 .IP
407 SVr4 used an array,
408 .IR \%acs_map ,
409 as does
410 .IR \%ncurses "."
411 NetBSD
412 .I curses
413 also uses an array,
414 actually named
415 .IR \%_acs_char ,
416 with a \%\*(``#define\*('' for compatibility.
417 .bP
418 HP-UX
419 .I curses
420 equates some of the
421 .I \%ACS_
422 symbols to the analogous
423 .I \%WACS_
424 symbols as if the
425 .I \%ACS_
426 symbols were wide characters
427 (see \fB\%add_wch\fP(3NCURSES)).
428 The misdefined symbols are the arrows and others that are not used for
429 line drawing.
430 .bP
431 X/Open Curses
432 (Issues\ 2 through 7)
433 has a typographical error
434 for the
435 .I \%ACS_LANTERN
436 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
437 (capital I),
438 while the header files for SVr4
439 .I curses
440 and other implementations use \*(``i\*(''
441 (small i).
442 .IP
443 None of the terminal descriptions on Unix platforms use uppercase I,
444 except for Solaris
445 (in its
446 .I \%term\%info
447 entry for \fI\%screen\fP(1),
448 apparently based on the X/Open documentation around 1995).
449 On the other hand,
450 its
451 .B \%gs6300
452 (AT&T PC6300 with EMOTS Terminal Emulator)
453 description uses lowercase i.
454 .PP
455 The
456 .I displayed
457 values of
458 .I \%ACS_
459 constants depend on
460 .bP
461 the
462 .I \%ncurses
463 ABI\(emfor example,
464 wide-character versus non-wide-character configurations
465 (the former is capable of displaying Unicode while the latter is not),
466 and
467 .bP
468 whether the locale uses UTF-8 encoding.
469 .PP
470 In certain cases,
471 the terminal is unable to display forms-drawing characters
472 .I except
473 by using UTF-8;
474 see the discussion of the
475 .I \%NCURSES_NO_UTF8_ACS
476 environment variable in \fB\%ncurses\fP(3NCURSES).
477 .SS "Character Set"
478 X/Open Curses assumes that the parameter passed to
479 .I \%waddch
480 contains a single character.
481 That character may have been more than eight bits wide in an SVr3 or
482 SVr4 implementation,
483 but X/Open Curses leaves the width of a non-wide character code
484 unspecified.
485 The standard further does not specify the internal structure of a
486 .IR chtype ","
487 though the use of bit operations to combine the character code with
488 attributes and a color pair identifier into a
489 .I \%chtype
490 for passage to
491 .I \%waddch
492 is common.
493 A portable application uses only the macros discussed in
494 \fB\%attr\fP(3NCURSES) to manipulate a
495 .IR \%chtype "."
496 .PP
497 In
498 .IR \%ncurses ,
499 .I \%chtype
500 holds an eight-bit character,
501 but the library allows a multibyte character sequence to be passed via a
502 succession of calls to
503 .IR \%waddch "."
504 Other implementations do not;
505 a
506 .I \%waddch
507 call transmits exactly one character,
508 which may be rendered in one or more screen locations depending on
509 whether it is printable
510 (see \fB\%unctrl\fP(3NCURSES)).
511 Depending on the locale,
512 .I \%ncurses
513 inspects the byte passed in each
514 .I \%waddch
515 call and checks whether the latest call continues a multibyte character.
516 When a character is
517 .IR complete ","
518 .I \%ncurses
519 displays the character and advances the cursor.
520 If the calling application interrupts the succession of bytes in
521 a multibyte character sequence by changing the current location\(emfor
522 example,
523 with \fB\%wmove\fP(3NCURSES)\(em\c
524 .I \%ncurses
525 discards the incomplete character.
526 .PP
527 For portability to other implementations,
528 do not rely upon the foregoing behavior.
529 Check whether a character can be represented as a single byte in the
530 current locale.
531 .bP
532 If it can,
533 call either
534 .I \%waddch
535 or
536 .IR \%wadd_wch "."
537 .bP
538 If it cannot,
539 use only
540 .IR \%wadd_wch "."
541 .SH HISTORY
542 4BSD (1980)
543 introduced
544 .I \%waddch
545 and its variants.
546 .PP
547 SVr3 (1987)
548 added the
549 .I \%echochar
550 and
551 .I \%wechochar
552 functions and most of the
553 .I ACS_
554 constants,
555 except for
556 .IR \%ACS_GEQUAL ","
557 .IR \%ACS_LEQUAL ","
558 .IR \%ACS_NEQUAL ","
559 .IR \%ACS_PI ","
560 .IR \%ACS_S3 ","
561 .IR \%ACS_S7 ","
562 and
563 .IR \%ACS_STERLING "."
564 .PP
565 .I \%ncurses
566 1.9.6 (1995)
567 furnished the remaining
568 .I ACS_
569 constants.
570 .SH SEE ALSO
571 \fB\%add_wch\fP(3NCURSES) describes comparable functions of the
572 .I \%ncurses
573 library in its wide-character configuration
574 .RI \%( ncursesw ).
575 .PP
576 \fB\%ncurses\fP(3NCURSES),
577 \fB\%addchstr\fP(3NCURSES),
578 \fB\%addstr\fP(3NCURSES),
579 \fB\%attr\fP(3NCURSES),
580 \fB\%bkgd\fP(3NCURSES),
581 \fB\%clear\fP(3NCURSES),
582 \fB\%inch\fP(3NCURSES),
583 \fB\%outopts\fP(3NCURSES),
584 \fB\%refresh\fP(3NCURSES),
585 \fB\%curses_variables\fP(3NCURSES),
586 \fB\%putchar\fP(3)