ncurses 6.4 - patch 20240323

[ncurses.git] / man / curs_addch.3x

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index b87f76637f61d803e667b8a86ca6a5c56977da64..f3eab27c8571f79ce75ca4729bcba82784fe1d37 100644 (file)
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *

 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -28,17 +28,23 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_addch.3x,v 1.76 2023/12/23 16:27:51 tom Exp $
-.TH curs_addch 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_addch.3x,v 1.81 2024/03/23 20:38:57 tom Exp $
+.TH curs_addch 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"

 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq

+.ds '  \(aq
+.ds ^  \(ha
+.ds ~  \(ti

 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""

+.ds       '  '
+.ds       ^  ^
+.ds       ~  ~

 .\}
 .
 .de bP
 .\}
 .
 .de bP


@@ -67,94 +73,149 @@ add a \fIcurses\fR character to a window and advance the cursor
 .fi
 .SH DESCRIPTION
 .SS "Adding Characters"
 .fi
 .SH DESCRIPTION
 .SS "Adding Characters"

-The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put
-the character \fIch\fP into the given window at its current window position,
-which is then advanced.
-They are analogous to the standard C library's \fI\%putchar\fP(3).
-If the advance is at the right margin:
-.bP
-The cursor automatically wraps to the beginning of the next line.
+.B \%waddch
+puts the character
+.I ch
+at the cursor position of window
+.IR win ,
+then advances the cursor position,
+analogously to the standard C library's \fI\%putchar\fP(3).
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+If advancement occurs at the right margin,

 .bP
 .bP

-At the bottom of the current scrolling region,
-and if \fB\%scrollok\fP(3X) is enabled,
-the scrolling region is scrolled up one line.
+the cursor automatically wraps to the beginning of the next line;
+and

 .bP
 .bP

-If \fB\%scrollok\fP(3X) is not enabled,
-writing a character at the lower right margin succeeds.
-However,
-an error is returned because it is not possible to wrap to a new line.
+at the bottom of the current scrolling region,
+and if \fB\%scrollok\fP(3X) is enabled for
+.IR win ,
+the scrolling region scrolls up one line.

 .PP
 .PP

-If \fIch\fP is a tab, newline, carriage return or backspace,
-the cursor is moved appropriately within the window:
+If
+.I ch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.

 .bP
 .bP

-Backspace moves the cursor one character left; at the left
-edge of a window it does nothing.
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.

 .bP
 .bP

-Carriage return moves the cursor to the window left margin on the current line.
+Carriage return moves the cursor to the left margin on the current line
+of the window.

 .bP
 .bP

-Newline does a \fBclrtoeol\fP,
-then moves the cursor to the window left margin on the next line,
-scrolling the window if on the last line.
+Line feed does a \fB\%clrtoeol\fP(3X),
+then moves the cursor to the left margin on the next line of the window,
+scrolling the window if the cursor was already on the last line.

 .bP
 .bP

-Tabs are considered to be at every eighth column.
-The tab interval may be altered by setting the \fBTABSIZE\fP variable.
+Tab advances the cursor to the next tab stop
+(possibly on the next line);
+these are placed at every eighth column by default.
+Alter the tab interval with the
+.B \%TABSIZE
+extension;
+see \fB\%curs_variables\fP(3X).

 .PP
 .PP

-If \fIch\fP is any other nonprintable character,
+If
+.I ch
+is any other nonprintable character,

 it is drawn in printable form,
 it is drawn in printable form,

-using the same convention as \fB\%unctrl\fP(3X):
+using the same convention as \fB\%unctrl\fP(3X).

 .bP
 .bP

-Control characters are displayed in the \fB^\fIX\fR notation.
+.B \%waddch
+displays control characters in
+.BI \*^ X
+notation.

 .bP
 .bP

-Values above 128 are either meta characters
+Character codes above 127 are either meta characters

 (if the screen has not been initialized,
 (if the screen has not been initialized,

-or if \fB\%meta\fP(3X) has been called with a \fBTRUE\fP E parameter),
-shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
-In the latter case, the values may not be printable;
+or if \fB\%meta\fP(3X) has been called with a
+.B TRUE
+.I bf
+parameter)
+that render in
+.BI M\- X
+notation,
+or they display as themselves.
+In the latter case,
+the values may not be printable;
+.\" XXX: The following claim could be clearer.

 this follows the X/Open specification.
 .PP
 this follows the X/Open specification.
 .PP

-Calling \fBwinch\fP after adding a
-nonprintable character does not return the character itself,
-but instead returns the printable representation of the character.
+Calling \fB\%winch\fP(3X) on the location of a nonprintable character
+does not return the character itself,
+but its \fB\%unctrl\fP(3X) representation.

 .PP
 Video attributes can be combined with a character argument passed to
 .PP
 Video attributes can be combined with a character argument passed to

-\fBaddch\fP or related functions by logical-ORing them into the character.
-(Thus, text, including attributes, can be copied from one place to another
-using \fB\%inch\fP(3X) and \fBaddch\fP.)
-See the \fB\%curs_attr\fP(3X) page for values of predefined video
-attribute constants that can be usefully OR'ed into characters.
+.B \%waddch
+by logical-ORing them into the character.
+(Thus,
+text,
+including attributes,
+can be copied from one place to another using \fB\%winch\fP(3X) and
+.BR \%waddch .)
+See \fB\%curs_attr\fP(3X) for values of predefined video attribute
+constants that can be usefully OR'ed with characters.

 .SS "Echoing Characters"
 .SS "Echoing Characters"

-The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
-\fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to \fBwaddch\fP
-followed by a call to \fBwrefresh\fP.
-The knowledge that only a single
-character is being output is used and, for non-control characters, a
-considerable performance gain may be seen by using these routines instead of
-their equivalents.
-.SS "Line Graphics"
-The following variables may be used to add line drawing characters to the
-screen with routines of the \fBaddch\fP family.
-The default character listed
-below is used if the \fBacsc\fP capability does not define a terminal-specific
-replacement for it,
-or if the terminal and locale configuration requires Unicode but the
-library is unable to use Unicode.
-.PP
-The names are taken from VT100 nomenclature.
+.B \%echochar
+and
+.B \%wechochar
+are equivalent to calling
+.RB \%( w ) addch
+followed by
+.RB \%( w ) refresh .
+.I curses
+interprets these functions as a hint that only a single character is
+being output;
+for non-control characters,
+a considerable performance gain may be enjoyed by employing them.
+.\" TODO: Combine the following with the "Line Drawing" subsection of
+.\" terminfo(5) and replace this with a cross reference there.
+.SS "Forms-Drawing Characters"
+.I curses
+defines macros starting with
+.B \%ACS_
+that can be used with
+.B \%waddch
+to write line-drawing and other special characters to the screen.
+.I \%ncurses
+terms these
+.I "forms-drawing characters."
+The ACS default listed below is used if the
+.B \%acs_chars
+.RB ( \%acsc )
+.I \%term\%info
+capability does not define a terminal-specific replacement for it,
+or if the terminal and locale configuration requires Unicode to access
+these characters but the library is unable to use Unicode.
+The \*(``acsc char\*('' column corresponds to how the characters are
+specified in the
+.B \%acs_chars
+string capability,
+and the characters in it may appear on the screen if the terminal's
+database entry incorrectly advertises ACS support.
+The name \*(``ACS\*('' originates in the Alternate Character Set feature
+of the DEC VT100 terminal.

 .PP
 .TS
 .PP
 .TS

-l l l l
-l l l l
-_ _ _ _
-l l l l.
-\fBACS\fP      \fBACS\fP       \fBacsc\fP      \fBGlyph\fP
-\fBName\fP     \fBDefault\fP   \fBchar\fP      \fBName\fP
+Lb Lb Lb Lb
+Lb Lb Lb Lb
+Lb L  L  Lx.
+\&     ACS     acsc    \&
+Symbol Default char    Glyph Name
+_

 ACS_BLOCK      #       0       solid square block
 ACS_BOARD      #       h       board of squares
 ACS_BTEE       +       v       bottom tee
 ACS_BLOCK      #       0       solid square block
 ACS_BOARD      #       h       board of squares
 ACS_BTEE       +       v       bottom tee

-ACS_BULLET     o       ~       bullet
+ACS_BULLET     o       \*~     bullet

 ACS_CKBOARD    :       a       checker board (stipple)
 ACS_DARROW     v       .       arrow pointing down
 ACS_CKBOARD    :       a       checker board (stipple)
 ACS_DARROW     v       .       arrow pointing down

-ACS_DEGREE     '       f       degree symbol
+ACS_DEGREE     \*'     f       degree symbol

 ACS_DIAMOND    +       \(ga    diamond
 ACS_GEQUAL     >       >       greater-than-or-equal-to
 ACS_HLINE      \-      q       horizontal line
 ACS_DIAMOND    +       \(ga    diamond
 ACS_GEQUAL     >       >       greater-than-or-equal-to
 ACS_HLINE      \-      q       horizontal line


@@ -176,154 +237,254 @@ ACS_S7  \-      r       scan line 7
 ACS_S9 \&_     s       scan line 9
 ACS_STERLING   f       }       pound-sterling symbol
 ACS_TTEE       +       w       top tee
 ACS_S9 \&_     s       scan line 9
 ACS_STERLING   f       }       pound-sterling symbol
 ACS_TTEE       +       w       top tee

-ACS_UARROW     ^       \-      arrow pointing up
+ACS_UARROW     \*^     \-      arrow pointing up

 ACS_ULCORNER   +       l       upper left-hand corner
 ACS_URCORNER   +       k       upper right-hand corner
 ACS_VLINE      |       x       vertical line
 .TE
 .SH RETURN VALUE
 ACS_ULCORNER   +       l       upper left-hand corner
 ACS_URCORNER   +       k       upper right-hand corner
 ACS_VLINE      |       x       vertical line
 .TE
 .SH RETURN VALUE

-All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success
-(the SVr4 manuals specify only
-\*(``an integer value other than \fBERR\fP\*('') upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.

 .PP
 .PP

-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+In
+.IR \%ncurses ,
+.B \%waddch
+returns
+.B ERR
+if it is not possible to add a complete character at the cursor
+position,
+as when conversion of a multibyte character to a byte sequence fails,
+or at least one of the resulting bytes cannot be added to the window.
+See section \*(``PORTABILITY\*('' below regarding the use of
+.B \%waddch
+with multibyte characters.

 .PP
 .PP

-If it is not possible to add a complete character,
-an error is returned:
-.bP

 If \fB\%scrollok\fP(3X) is not enabled,
 If \fB\%scrollok\fP(3X) is not enabled,

-writing a character at the lower right margin succeeds.
+.B \%waddch
+can successfully write a character at the bottom right location of the
+window.

 However,
 However,

-an error is returned because it is not possible to wrap to a new line.
-.bP
-If an error is detected when converting a multibyte character to a sequence
-of bytes,
-or if it is not possible to add all of the resulting bytes in the window,
-an error is returned.
+.I \%ncurses
+returns
+.B ERR
+because it is not possible to wrap to a new line.
+.PP
+Functions with a \*(``mv\*('' prefix first perform cursor movement using
+\fB\%wmove\fP(3X) and fail if the position is outside the window,
+or
+(for \*(``mvw\*('' functions)
+if the
+.I \%WINDOW
+pointer is null.

 .SH NOTES
 .SH NOTES

-Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
-\fBechochar\fP may be macros.
+.BR \%addch ,
+.BR \%mvaddch ,
+.BR \%mvwaddch ,
+and
+.B \%echochar
+may be implemented as macros.

 .SH PORTABILITY
 .SH PORTABILITY

-These functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+The defaults specified for forms-drawing characters apply in the POSIX
+locale.

 .SS "ACS Symbols"
 .SS "ACS Symbols"

-X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants.
-For the wide-character implementation (see \fBcurs_add_wch\fP),
-there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants.
-Some implementations are problematic:
+X/Open Curses states that the
+.B \%ACS_
+definitions are
+.I char
+constants.
+.PP
+Some implementations are problematic.

 .bP
 .bP

-Some implementations define the ACS symbols to a constant
-(such as Solaris), while others define those to entries in an array.
+Solaris
+.IR curses ,
+for example,
+define the ACS symbols as constants;
+others define them as elements of an array.

 .IP
 .IP

-This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
-NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
+This implementation uses an array,
+.BR \%acs_map ,
+as did SVr4
+.IR curses .
+NetBSD also uses an array,
+actually named
+.BR \%_acs_char ,
+with a
+.B \%#define

 for compatibility.
 .bP
 for compatibility.
 .bP

-HP-UX curses equates some of the \fBACS_\fP symbols
-to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
-wide characters.
-The misdefined symbols are the arrows
-and other symbols which are not used for line-drawing.
+HP-UX
+.I curses
+equates some of the
+.B \%ACS_
+symbols to the analogous
+.B \%WACS_
+symbols as if the
+.B \%ACS_
+symbols were wide characters
+(see \fB\%curs_add_wch\fP(3X)).
+The misdefined symbols are the arrows and others that are not used for
+line drawing.

 .bP
 .bP

-X/Open Curses (issues 2 through 7) has a typographical error
-for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
-to \fBI\fP (capital I), while the header files for SVr4 curses
-and the various implementations use \fBi\fP (lowercase).
+X/Open Curses
+(Issues 2 through 7)
+has a typographical error
+for the
+.B \%ACS_LANTERN
+symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
+(capital I),
+while the header files for SVr4
+.I curses
+and other implementations use \*(``i\*(''
+(small i).

 .IP
 .IP

-None of the terminal descriptions on Unix platforms use uppercase-I,
-except for Solaris (i.e., \fBscreen\fP's terminal description,
+None of the terminal descriptions on Unix platforms use uppercase I,
+except for Solaris
+(in its
+.I \%term\%info
+entry for \fI\%screen\fP(1),

 apparently based on the X/Open documentation around 1995).
 apparently based on the X/Open documentation around 1995).

-On the other hand, the terminal description \fIgs6300\fP
-(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
-.LP
+On the other hand,
+its
+.B \%gs6300
+(AT&T PC6300 with EMOTS Terminal Emulator)
+description uses lowercase i.
+.PP

 Some ACS symbols
 Some ACS symbols

-(ACS_S3,
-ACS_S7,
-ACS_LEQUAL,
-ACS_GEQUAL,
-ACS_PI,
-ACS_NEQUAL,
-ACS_STERLING)
-were not documented in
-any publicly released System V.
-However, many publicly available terminfos
-include \fBacsc\fP strings in which their key characters (pryz{|}) are
-embedded, and a second-hand list of their character descriptions has come
-to light.
-The ACS-prefixed names for them were invented for \fB\%ncurses\fP(3X).
-.LP
-The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants
-depend on
+.RB ( \%ACS_S3 ,
+.BR \%ACS_S7 ,
+.BR \%ACS_LEQUAL ,
+.BR \%ACS_GEQUAL ,
+.BR \%ACS_PI ,
+.BR \%ACS_NEQUAL ,
+and
+.BR \%ACS_STERLING )
+were not documented in any publicly released System\ V.
+However,
+many publicly available
+.I \%term\%info
+entries include
+.B \%acsc
+strings in which their key characters (pryz{|}) are embedded,
+and a second-hand list of their character descriptions has come to
+light.
+The
+.I \%ncurses
+developers invented ACS-prefixed names for them.
+.PP
+The
+.I displayed
+values of
+.B \%ACS_
+constants depend on

 .bP
 .bP

-the library configuration,
-i.e.,
-\fI\%ncurses\fP versus \fI\%ncursesw\fP,
-where the latter is capable of displaying Unicode while the former is not, and
+the
+.I \%ncurses
+ABI\(emfor example,
+wide-character versus non-wide-character configurations
+(the former is capable of displaying Unicode while the latter is not),
+and

 .bP
 .bP

-whether the \fIlocale\fP uses UTF-8 encoding.
-.LP
-In certain cases, the terminal is unable to display line-drawing characters
-except by using UTF-8
-(see the discussion of \fB\%NCURSES_NO_UTF8_ACS\fP in
-\fB\%ncurses\fP(3X)).
+whether the locale uses UTF-8 encoding.
+.PP
+In certain cases,
+the terminal is unable to display forms-drawing characters
+.I except
+by using UTF-8;
+see the discussion of the
+.I \%NCURSES_NO_UTF8_ACS
+environment variable in \fB\%ncurses\fP(3X)).

 .SS "Character Set"
 .SS "Character Set"

-X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
-a single character.
-As discussed in \fB\%curs_attr\fP(3X), that character may have been
-more than eight bits in an SVr3 or SVr4 implementation,
-but in the X/Open Curses model, the details are not given.
-The important distinction between SVr4 curses and X/Open Curses is
-that the non-character information (attributes and color) was
-separated from the character information which is packed in a \fBchtype\fP
-to pass to \fBwaddch\fP.
+X/Open Curses assumes that the parameter passed to
+.B \%waddch
+contains a single character.
+As discussed in \fB\%curs_attr\fP(3X),
+that character may have been more than eight bits wide in an SVr3 or
+SVr4 implementation,
+but in the X/Open Curses model,
+the details are not given.
+The important distinction between SVr4
+.I curses
+and X/Open Curses is that the latter separates non-character information
+(attributes and color)
+from the character code,
+which SVr4 packs into a
+.I \%chtype
+for passage to
+.BR \%waddch .

 .PP
 .PP

-In this implementation, \fBchtype\fP holds an eight-bit character.
-But \fI\%ncurses\fP allows multibyte characters to be passed in a
-succession of calls to \fBwaddch\fP.
-The other implementations do not do this;
-a call to \fBwaddch\fP passes exactly one character
-which may be rendered as one or more cells on the screen
-depending on whether it is printable.
+In
+.IR \%ncurses ,
+.I \%chtype
+holds an eight-bit character.
+But
+.I \%ncurses
+allows a multibyte character to be passed in a succession of calls to
+.BR \%waddch .
+Other implementations do not;
+a
+.B \%waddch
+call transmits exactly one character,
+which may be rendered in one or more screen locations depending on
+whether it is printable.

 .PP
 Depending on the locale settings,
 .PP
 Depending on the locale settings,

-\fI\%ncurses\fP will inspect the byte passed in each call to \fBwaddch\fP,
-and check if the latest call will continue a multibyte sequence.
-When a character is \fIcomplete\fP,
-\fI\%ncurses\fP displays the character and moves to the next position in the screen.
+.I \%ncurses
+inspects the byte passed in each
+.B \%waddch
+call,
+and checks whether the latest call continues a multibyte sequence.
+When a character is
+.IR complete ,
+.I \%ncurses
+displays the character and advances the window's current location.

 .PP
 If the calling application interrupts the succession of bytes in
 .PP
 If the calling application interrupts the succession of bytes in

-a multibyte character by moving the current location (e.g., using \fBwmove\fP),
-\fI\%ncurses\fP discards the partially built character,
-starting over again.
+a multibyte character sequence by moving the current location
+(for example,
+with \fB\%wmove\fP(3X)),
+.I \%ncurses
+discards the incomplete character.

 .PP
 For portability to other implementations,
 .PP
 For portability to other implementations,

-do not rely upon this behavior:
+do not rely upon this behavior.
+Check whether a character can be represented as a single byte in the
+current locale.

 .bP
 .bP

-check if a character can be represented as a single byte in the current locale
-before attempting call \fBwaddch\fP, and
+If it can,
+call either
+.B \%waddch
+or \fB\%wadd_wch\fP(3X).

 .bP
 .bP

-call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+If it cannot,
+use only
+\fB\%wadd_wch\fP(3X).

 .SS TABSIZE
 .SS TABSIZE

-The \fBTABSIZE\fP variable is implemented in SVr4 and other versions of curses,
-but is not part of X/Open curses
-(see \fBcurs_variables\fP(3X) for more details).
-.LP
-If \fIch\fP is a carriage return,
-the cursor is moved to the beginning of the current row of the window.
-This is true of other implementations, but is not documented.
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it
+(see \fB\%curs_variables\fP(3X)).

 .SH SEE ALSO
 \fB\%curses\fP(3X),
 .SH SEE ALSO
 \fB\%curses\fP(3X),

+\fB\%curs_addchstr\fP(3X),
+\fB\%curs_addstr\fP(3X),

 \fB\%curs_attr\fP(3X),
 \fB\%curs_clear\fP(3X),
 \fB\%curs_inch\fP(3X),
 \fB\%curs_outopts\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_variables\fP(3X),
 \fB\%curs_attr\fP(3X),
 \fB\%curs_clear\fP(3X),
 \fB\%curs_inch\fP(3X),
 \fB\%curs_outopts\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_variables\fP(3X),

-\fB\%putc\fP(3)
+\fB\%putchar\fP(3)

 .PP
 .PP

-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fB\%curs_add_wch\fP(3X).
+\fB\%curs_add_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).