'\" 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.55 2020/10/24 09:12:31 tom Exp $
.TH curs_addch 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.SH SYNOPSIS
\fB#include <curses.h>\fR
.PP
-\fBint addch(const chtype ch);\fR
+\fBint addch(const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint waddch(WINDOW *win, const chtype ch);\fR
+\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint mvaddch(int y, int x, const chtype ch);\fR
+\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
+\fBint mvwaddch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR
+.sp
+\fBint echochar(const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint echochar(const chtype ch);\fR
-.br
-\fBint wechochar(WINDOW *win, const chtype ch);\fR
+\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
.SH DESCRIPTION
.SS Adding characters
Tabs are considered to be at every eighth column.
The tab interval may be altered by setting the \fBTABSIZE\fR variable.
.PP
-If \fIch\fR is any other control character, it
-is drawn in \fB^\fR\fIX\fR notation.
+If \fIch\fR is any other nonprintable character,
+it is drawn in printable form,
+i.e., the \fB^\fR\fIX\fR notation used by \fBunctrl\fR(3X).
Calling \fBwinch\fR after adding a
-control character does not return the character itself, but instead returns
-the ^-representation of the control character.
+nonprintable character does not return the character itself,
+but instead returns the printable representation of the character.
.PP
Video attributes can be combined with a character argument passed to
\fBaddch\fR or related functions by logical-ORing them into the character.
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;