* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp @
+ * @Id: curs_addch.3x,v 1.88 2024/05/25 21:13:32 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_addch 3x 2024-05-25 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_addch 3x 2024-05-25 ncurses 6.5 Library calls</H1>
<PRE>
<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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-</PRE><H3><a name="h3-
Adding-Characters">Adding Characters</a></H3><PRE>
- <STRONG>waddch</STRONG> puts the character <EM>ch</EM> at the cursor position of window <EM>win</EM>, then
- advances the cursor position, analogously to the standard C library's
+</PRE><H3><a name="h3-
waddch">waddch</a></H3><PRE>
+ <STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances
+ the cursor position, analogously to the standard C library's
<STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
If advancement occurs at the right margin,
- <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line;
- and
+ <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line,
+ then,
- <STRONG>o</STRONG> at the bottom of the current scrolling region, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>
- is enabled for <EM>win</EM>, the scrolling region scrolls up one line.
+ <STRONG>o</STRONG> if it was at the bottom of the scrolling region, and if
+ <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled for <EM>win</EM>, the scrolling region scrolls up
+ one line.
- If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
+ If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
moves appropriately within the window.
- <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
+ <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
of a window, it does nothing.
- <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
+ <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
line of the window.
- <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then moves the cursor to the left
- margin on the next line of the window, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is
- enabled for <EM>win</EM>, scrolls the window if the cursor was already on
- the last line.
+ <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
+ margin.
- <STRONG>o</STRONG> 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 <STRONG>TABSIZE</STRONG> extension; see
+ <STRONG>o</STRONG> 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 <STRONG>TABSIZE</STRONG> extension; see
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
- If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
- form
, using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.
+ If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
+ 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 location of a nonprintable character does not
+ Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not
return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
- <EM>ch</EM> may contain rendering and/or color attributes, and others can be
- combined with the parameter by logically "or"ing with it. (A character
- with its attributes can be copied from place to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG>
- and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined video
- attribute constants that can be usefully "or"ed with characters.
+ The object or expression <EM>ch</EM> may contain attributes and/or a color pair
+ identifier. (A character with its attributes can be copied from place
+ to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of
+ predefined video attribute constants that can be usefully "or"ed with
+ characters.
-</PRE><H3><a name="h3-
Echoing-Characters">Echoing Characters</a></H3><PRE>
- <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
- (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
+</PRE><H3><a name="h3-
wechochar">wechochar</a></H3><PRE>
+ <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
+ (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> 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.
</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
- <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
- to write line-drawing and other special characters to the screen.
- <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
- below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
- define a terminal-specific replacement for it, or if the terminal and
- locale configuration requires Unicode to access these characters but
+ <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
+ to write line-drawing and other special characters to the screen.
+ <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
+ below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> 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 <STRONG>acs_chars</STRONG> 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.
+ corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
+ string capability, and the characters in it may appear on the screen if
+ the terminal type's database entry incorrectly advertises ACS support.
+ The name "ACS" originates in the Alternate Character Set feature of the
+ DEC VT100 terminal.
<STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
<STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
- In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> 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 <STRONG>waddch</STRONG> with multibyte characters.
+ In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if
- <STRONG>waddch</STRONG> can successfully write a character at the bottom right location
- of the window. However, <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not
- enabled in that event, because it is not possible to wrap to a new
- line.
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG>,
+
+ <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
+ been called on <EM>win</EM> when a write to its bottom right location is
+ attempted, or
+
+ <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
+ position.
+
+ The last may be due to different causes:
+
+ <STRONG>o</STRONG> conversion of a multibyte character to a byte sequence can fail, or
+
+ <STRONG>o</STRONG> at least one of the bytes resulting from conversion from a
+ multibyte sequence cannot be added to the window. See section
+ "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with multibyte
+ characters.
Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
<STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+
+</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
+ SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
+ X/Open Curses does not specify it; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
+
+
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- X/Open Curses, Issue 4 describes these functions. It specifies no
+ X/Open Curses, Issue 4 describes these functions. It specifies no
error conditions for them.
- SVr4 <EM>curses</EM> describes a successful return value only as "an integer
+ SVr4 <EM>curses</EM> describes a successful return value only as "an integer
value other than <STRONG>ERR</STRONG>".
- The defaults specified for forms-drawing characters apply in the POSIX
+ The defaults specified for forms-drawing characters apply in the POSIX
locale.
Some implementations are problematic.
- <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants;
+ <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants;
others define them as elements of an array.
- This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
+ This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
for compatibility.
- <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
- <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
- <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
+ <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
+ <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
+ <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
others that are not used for line drawing.
- <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
- the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
- (capital I), while the header files for SVr4 <EM>curses</EM> and other
+ <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
+ the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
+ (capital I), while the header files for SVr4 <EM>curses</EM> and other
implementations use "i" (small i).
- None of the terminal descriptions on Unix platforms use uppercase
- I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
- apparently based on the X/Open documentation around 1995). On the
- other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
+ None of the terminal descriptions on Unix platforms use uppercase
+ I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
+ apparently based on the X/Open documentation around 1995). On the
+ other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
description uses lowercase i.
- Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
- <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
- released System V. However, many publicly available <EM>terminfo</EM> entries
- include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are
- embedded, and a second-hand list of their character descriptions has
- come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
+ Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
+ <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
+ released System V. However, many publicly available <EM>terminfo</EM> entries
+ include <STRONG>acsc</STRONG> capabilities in which their key characters (<STRONG>pryz{|}</STRONG>) are
+ embedded, and a second-hand list of their character descriptions has
+ come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
them.
The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
<STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
- character configurations (the former is capable of displaying
+ character configurations (the former is capable of displaying
Unicode while the latter is not), and
<STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
- In certain cases, the terminal is unable to display forms-drawing
- characters <EM>except</EM> by using UTF-8; see the discussion of the
- <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>).
+ In certain cases, the terminal is unable to display forms-drawing
+ characters <EM>except</EM> by using UTF-8; see the discussion of the
+ <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>.
</PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
- X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
- single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, 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 <EM>curses</EM> and X/Open Curses is that the
- latter separates non-character information (attributes and color) from
- the character code, which SVr4 packs into a <EM>chtype</EM> for passage to
- <STRONG>waddch</STRONG>.
-
- In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library
- allows a multibyte character to be passed in a succession of calls to
- <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly
- one character, which may be rendered in one or more screen locations
- depending on whether it is printable.
-
- Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in
- each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a
- multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
- character and advances the cursor.
-
- If the calling application interrupts the succession of bytes in a
- multibyte character sequence by changing the current location--for
+ X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
+ single character. That character may have been more than eight bits
+ wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the
+ width of a non-wide character code unspecified. The standard further
+ does not specify the internal structure of a <EM>chtype</EM>, though the use of
+ bit operations to combine the character code with attributes and a
+ color pair identifier into a <EM>chtype</EM> for passage to <STRONG>waddch</STRONG> is common. A
+ portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to
+ manipulate a <EM>chtype</EM>.
+
+ In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows
+ a multibyte character to be passed in a succession of calls to <STRONG>waddch</STRONG>.
+ Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly one
+ character, which may be rendered in one or more screen locations
+ depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>). Depending on
+ the locale, <EM>ncurses</EM> inspects the byte passed in each <STRONG>waddch</STRONG> call and
+ checks whether the latest call continues a multibyte sequence. When a
+ character is <EM>complete</EM>, <EM>ncurses</EM> displays the character and advances the
+ cursor. If the calling application interrupts the succession of bytes
+ in a multibyte character sequence by changing the current location--for
example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character.
- For portability to other implementations, do not rely upon this
- behavior. Check whether a character can be represented as a single
- byte in the current locale.
+ For portability to other implementations, do not rely upon the
+ foregoing behavior. Check whether a character can be represented as a
+ single byte in the current locale.
<STRONG>o</STRONG> If it can, call either <STRONG>waddch</STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
<STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
-</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
- X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
-
-
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
in its wide-character configuration (<EM>ncursesw</EM>).
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-25 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
-<li><a href="#h3-Adding-Characters">Adding Characters</a></li>
-<li><a href="#h3-Echoing-Characters">Echoing Characters</a></li>
+<li><a href="#h3-waddch">waddch</a></li>
+<li><a href="#h3-wechochar">wechochar</a></li>
<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a>
+<ul>
+<li><a href="#h3-TABSIZE">TABSIZE</a></li>
+</ul>
+</li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
<li><a href="#h3-Character-Set">Character Set</a></li>
-<li><a href="#h3-TABSIZE">TABSIZE</a></li>
</ul>
</li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
projects / ncurses.git / blobdiff