'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.30 2010/10/02 23:19:07 tom Exp $
-.TH curs_addch 3X ""
+.\" $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
+.ds ' \(aq
+.ds ^ \(ha
+.ds ~ \(ti
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ' '
+.ds ^ ^
+.ds ~ ~
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBaddch\fR,
-\fBwaddch\fR,
-\fBmvaddch\fR,
-\fBmvwaddch\fR,
-\fBechochar\fR,
-\fBwechochar\fR \- add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
+\fB\%addch\fP,
+\fB\%waddch\fP,
+\fB\%mvaddch\fP,
+\fB\%mvwaddch\fP,
+\fB\%echochar\fP,
+\fB\%wechochar\fP \-
+add a \fIcurses\fR character to a window and advance the cursor
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.PP
-\fBint addch(const chtype ch);\fR
-.br
-\fBint waddch(WINDOW *win, const chtype ch);\fR
-.br
-\fBint mvaddch(int y, int x, const chtype ch);\fR
-.br
-\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
-.br
-\fBint echochar(const chtype ch);\fR
-.br
-\fBint wechochar(WINDOW *win, const chtype ch);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint addch(const chtype \fIch\fP);
+\fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+\fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+\fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+.PP
+\fBint echochar(const chtype \fIch\fP);
+\fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+.fi
.SH DESCRIPTION
-The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
-the character \fIch\fR into the given window at its current window position,
-which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3).
-If the advance is at the right margin, the cursor automatically wraps to the
-beginning of the next line. At the bottom of the current scrolling region, if
-\fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
-.PP
-If \fIch\fR is a tab, newline, or backspace,
-the cursor is moved appropriately within the window.
-Backspace moves the cursor one character left; at the left
-edge of a window it does nothing.
-Newline does a \fBclrtoeol\fR,
-then moves the cursor to the window left margin on the next line,
-scrolling the window if on the last line.
-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 control character other than tab, newline, or backspace, it
-is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
-control character does not return the character itself, but instead returns
-the ^-representation of the control character.
+.SS "Adding Characters"
+.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
+the cursor automatically wraps to the beginning of the next line;
+and
+.bP
+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
+If
+.I ch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.
+.bP
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.
+.bP
+Carriage return moves the cursor to the left margin on the current line
+of the window.
+.bP
+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
+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
+If
+.I ch
+is any other nonprintable character,
+it is drawn in printable form,
+using the same convention as \fB\%unctrl\fP(3X).
+.bP
+.B \%waddch
+displays control characters in
+.BI \*^ X
+notation.
+.bP
+Character codes above 127 are either meta characters
+(if the screen has not been initialized,
+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
+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
-\fBaddch\fR or related functions by logical-ORing them into the character.
-(Thus, text, including attributes, can be copied from one place to another
-using \fBinch\fR and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for
-values of predefined video attribute constants that can be usefully OR'ed
-into characters.
-.PP
-The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
-\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
-followed by a call to \fBwrefresh\fR. 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\fR family. The default character listed
-below is used if the \fBacsc\fR capability does not define a terminal-specific
-replacement for it.
-The names are taken from VT100 nomenclature.
+.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"
+.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
-l l l
-_ _ _
-l l l.
-\fIName\fR \fIDefault\fR \fIDescription\fR
-ACS_BLOCK # solid square block
-ACS_BOARD # board of squares
-ACS_BTEE + bottom tee
-ACS_BULLET o bullet
-ACS_CKBOARD : checker board (stipple)
-ACS_DARROW v arrow pointing down
-ACS_DEGREE ' degree symbol
-ACS_DIAMOND + diamond
-ACS_GEQUAL > greater-than-or-equal-to
-ACS_HLINE \- horizontal line
-ACS_LANTERN # lantern symbol
-ACS_LARROW < arrow pointing left
-ACS_LEQUAL < less-than-or-equal-to
-ACS_LLCORNER + lower left-hand corner
-ACS_LRCORNER + lower right-hand corner
-ACS_LTEE + left tee
-ACS_NEQUAL ! not-equal
-ACS_PI * greek pi
-ACS_PLMINUS # plus/minus
-ACS_PLUS + plus
-ACS_RARROW > arrow pointing right
-ACS_RTEE + right tee
-ACS_S1 \- scan line 1
-ACS_S3 \- scan line 3
-ACS_S7 \- scan line 7
-ACS_S9 \&_ scan line 9
-ACS_STERLING f pound-sterling symbol
-ACS_TTEE + top tee
-ACS_UARROW ^ arrow pointing up
-ACS_ULCORNER + upper left-hand corner
-ACS_URCORNER + upper right-hand corner
-ACS_VLINE | vertical line
+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_BULLET o \*~ bullet
+ACS_CKBOARD : a checker board (stipple)
+ACS_DARROW v . arrow pointing down
+ACS_DEGREE \*' f degree symbol
+ACS_DIAMOND + \(ga diamond
+ACS_GEQUAL > > greater-than-or-equal-to
+ACS_HLINE \- q horizontal line
+ACS_LANTERN # i lantern symbol
+ACS_LARROW < , arrow pointing left
+ACS_LEQUAL < y less-than-or-equal-to
+ACS_LLCORNER + m lower left-hand corner
+ACS_LRCORNER + j lower right-hand corner
+ACS_LTEE + t left tee
+ACS_NEQUAL ! | not-equal
+ACS_PI * { greek pi
+ACS_PLMINUS # g plus/minus
+ACS_PLUS + n plus
+ACS_RARROW > + arrow pointing right
+ACS_RTEE + u right tee
+ACS_S1 \- o scan line 1
+ACS_S3 \- p scan line 3
+ACS_S7 \- r scan line 7
+ACS_S9 \&_ s scan line 9
+ACS_STERLING f } pound-sterling symbol
+ACS_TTEE + w top tee
+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
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
-.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.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+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
+If \fB\%scrollok\fP(3X) is not enabled,
+.B \%waddch
+can successfully write a character at the bottom right location of the
+window.
+However,
+.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
-Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
-\fBechochar\fR may be macros.
+.BR \%addch ,
+.BR \%mvaddch ,
+.BR \%mvwaddch ,
+and
+.B \%echochar
+may be implemented as macros.
.SH PORTABILITY
-All these functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
-.LP
+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"
+X/Open Curses states that the
+.B \%ACS_
+definitions are
+.I char
+constants.
+.PP
+Some implementations are problematic.
+.bP
+Solaris
+.IR curses ,
+for example,
+define the ACS symbols as constants;
+others define them as elements of an array.
+.IP
+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
+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
+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
+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).
+On the other hand,
+its
+.B \%gs6300
+(AT&T PC6300 with EMOTS Terminal Emulator)
+description uses lowercase i.
+.PP
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\fR 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 \fBncurses\fR(3X).
-.LP
-The \fBTABSIZE\fR variable is implemented in some versions of curses,
-but is not part of X/Open curses.
-.LP
-If \fIch\fR 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.
+.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
+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
+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"
+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
+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,
+.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
+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,
+do not rely upon this behavior.
+Check whether a character can be represented as a single byte in the
+current locale.
+.bP
+If it can,
+call either
+.B \%waddch
+or \fB\%wadd_wch\fP(3X).
+.bP
+If it cannot,
+use only
+\fB\%wadd_wch\fP(3X).
+.SS TABSIZE
+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
-\fBcurses\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_inch\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBputc\fR(3).
-.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_add_wch\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\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\%putchar\fP(3)
+.PP
+\fB\%curs_add_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
projects / ncurses.git / blobdiff