'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey *
+.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.47 2019/02/16 23:50:17 tom Exp $
+.\" $Id: curs_addch.3x,v 1.52 2020/03/21 23:47:23 tom Exp $
.TH curs_addch 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
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.
+.PP
+If it is not possible to add a complete character,
+an error is returned:
+.bP
+If \fBscrollok\fR 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
+.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.
.SH NOTES
Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
\fBechochar\fR may be macros.
X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants.
For the wide-character implementation (see \fBcurs_add_wch\fP),
there are analogous \fIWACS_\fP definitions which are \fBcchar_t\fP constants.
+Some implementations are problematic:
+.bP
+Some implementations define the ACS symbols to a constant
+(such as Solaris), while others define those to entries in an array.
+.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
+for compatibility.
+.bP
+HPUX curses equates some of the \fIACS_\fP symbols
+to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were
+wide characters.
+The misdefined symbols are the arrows
+and other symbols which are not used for line-drawing.
+.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).
+.IP
+None of the terminal descriptions on Unix platforms use uppercase-I,
+except for Solaris (i.e., \fIscreen\fP's terminal description,
+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
Some ACS symbols
(ACS_S3,
separated from the character information which is packed in a \fBchtype\fP
to pass to \fBwaddch\fP.
.PP
-In this implementation, \fBchtype\fP holds eight bits.
+In this implementation, \fBchtype\fP holds an eight-bit character.
But ncurses allows multibyte characters to be passed in a succession
of calls to \fBwaddch\fP.
The other implementations do not do this;