# curs_addch 3x 2025-08-16 ncurses 6.5 Library calls

    curs_addch(3x)                   Library calls                  curs_addch(3x)

## NAME

           addch,  waddch,  mvaddch,  mvwaddch, echochar, wechochar - add a curses
           character to a window and advance the cursor

## SYNOPSIS

           #include <curses.h>

           int addch(const chtype ch);
           int waddch(WINDOW * win, const chtype ch);
           int mvaddch(int y, int x, const chtype ch);
           int mvwaddch(WINDOW * win, int y, int x, const chtype ch);

           int echochar(const chtype ch);
           int wechochar(WINDOW * win, const chtype ch);

           /* (integer) constants */
           /* ... */ ACS_BLOCK;
           /* ... */ ACS_BOARD;
           /* ... */ ACS_BTEE;
           /* ... */ ACS_BULLET;
           /* ... */ ACS_CKBOARD;
           /* ... */ ACS_DARROW;
           /* ... */ ACS_DEGREE;
           /* ... */ ACS_DIAMOND;
           /* ... */ ACS_HLINE;
           /* ... */ ACS_LANTERN;
           /* ... */ ACS_LARROW;
           /* ... */ ACS_LLCORNER;
           /* ... */ ACS_LRCORNER;
           /* ... */ ACS_LTEE;
           /* ... */ ACS_PLMINUS;
           /* ... */ ACS_PLUS;
           /* ... */ ACS_RARROW;
           /* ... */ ACS_RTEE;
           /* ... */ ACS_S1;
           /* ... */ ACS_S9;
           /* ... */ ACS_TTEE;
           /* ... */ ACS_UARROW;
           /* ... */ ACS_ULCORNER;
           /* ... */ ACS_URCORNER;
           /* ... */ ACS_VLINE;
           /* extensions */
           /* ... */ ACS_GEQUAL;
           /* ... */ ACS_LEQUAL;
           /* ... */ ACS_NEQUAL;
           /* ... */ ACS_PI;
           /* ... */ ACS_S3;
           /* ... */ ACS_S7;
           /* ... */ ACS_STERLING;

## DESCRIPTION

### waddch

           waddch writes the curses character ch to the window win, then  advances
           the   cursor   position,   analogously  to  the  standard  C  library's
           putchar(3).  ncurses(3x) describes the variants of this function.

           Construct a curses character from a char  by  assignment  or  typecast.
           Subsection "Video Attributes" of attron(3x) describes how to manipulate
           its attributes and color pair.  (A color pair selection is not  honored
           unless initialized; see start_color(3x).)

           The  object or expression ch may contain attributes and/or a color pair
           identifier.  (A  chtype  can  be  copied  from  place  to  place  using
           winch(3x)   and   waddch.)    curses   defines  constants  to  aid  the
           manipulation of character attributes; see curs_attr(3x).   A  ch  whose
           character  component  is a space, and whose only attribute is A_NORMAL,
           is  a  blank  character,  and  therefore  combines  with  the  window's
           background character; see curs_bkgd(3x).

           If  ch  is  a backspace, carriage return, line feed, or tab, the cursor
           moves appropriately within the window.

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

           o   Carriage  return  moves  the  cursor to the left margin on the same
               line of the window.

           o   Line feed does a clrtoeol(3x), then advances as if from  the  right
               margin.

           o   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   TABSIZE   extension;   see
               curs_variables(3x).

           If ch is any other nonprintable character, curses draws it in printable
           form using the same convention as unctrl(3x).  Calling winch(3x) on the
           location  of  a  nonprintable  character  does not return the character
           itself, but its unctrl(3x) representation.

           Adding printable characters with waddch causes it to wrap at the  right
           margin of the window:

           o   If  the  cursor  is  not  at the bottom of the scrolling region and
               advancement occurs at the right margin,  the  cursor  automatically
               wraps to the beginning of the next line.

           o   If  the  cursor  is  at  the  bottom  of  the scrolling region when
               advancement occurs at the right margin, and scrollok(3x) is enabled
               for  win,  the  scrolling region scrolls up one line and the cursor
               wraps as above.  Otherwise, advancement and scrolling do not occur,
               and waddch returns ERR.

           A  window's  margins may coincide with the screen boundaries.  This may
           be a problem when ncurses  updates  the  screen  to  match  the  curses
           window.   When  their  right  and bottom margins coincide, ncurses uses
           different strategies to handle the variations of scrolling and wrapping
           at the lower-right corner by depending on the terminal capabilities:

           o   If the terminal does not automatically wrap as characters are added
               at the right margin (i.e., auto right margins), ncurses writes  the
               character directly.

           o   If  the  terminal has auto right margins, but also has capabilities
               for turning auto margins off and on, ncurses turns the auto  margin
               feature off temporarily when writing to the lower-right corner.

           o   If  the  terminal has an insertion mode which can be turned off and
               on, ncurses  writes  the  character  just  before  the  lower-right
               corner,  and  then  inserts a character to push the update into the
               corner.

### wechochar

           echochar and wechochar are equivalent to calling (w)addch  followed  by
           (w)refresh  on stdscr or the specified window.  curses interprets these
           functions as a hint to its optimizer that only a single character  cell
           in  the  window  is  being  altered  between refreshes; for non-control
           characters, a considerable performance gain may be enjoyed by employing
           them.

### Forms-Drawing Characters

           curses  defines  macros starting with ACS_ that can be used with waddch
           to write line-drawing and other symbols to the screen.   ncurses  terms
           these  forms-drawing  characters.   curses  uses the ACS default listed
           below if the terminal type lacks the acs_chars (acsc) capability;  that
           capability  does  not define a replacement for the character; or if the
           terminal type and locale configuration require 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 acs_chars
           (acsc)  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.

                          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    +         `      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

## RETURN VALUE

           These functions return OK on success and ERR on failure.

           In ncurses, these functions fail if

           o   the curses screen has not been initialized,

           o   (for functions taking a WINDOW pointer  argument)  win  is  a  null
               pointer,

           o   wrapping  to  a new line is impossible because scrollok(3x) has not
               been called on win (or stdscr, as applicable) when a write  to  its
               bottom right location is attempted, or

           o   it  is  not  possible  to  add  a  complete character at the cursor
               position.

           The last may be due to different causes:

           o   conversion of a wide character to a  multibyte  character  sequence
               can fail, or

           o   at  least one of the bytes resulting from wide character conversion
               to a multibyte character sequence cannot be added  to  the  window.
               See  section  "PORTABILITY"  below regarding the use of waddch with
               wide characters.

           Functions prefixed with "mv" first perform cursor movement and fail  if
           the position (y, x) is outside the window boundaries.

## NOTES

           addch, mvaddch, mvwaddch, and echochar may be implemented as macros.

## EXTENSIONS

           The symbols ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI, ACS_NEQUAL,
           and ACS_STERLING were not documented in any publicly released  System V
           and  are  not  standard.   However,  many  publicly  available terminfo
           entries include  acs_chars  (acsc)  capabilities  in  which  their  key
           characters  (pryz{|})  are  embedded,  and  a second-hand list of their
           character descriptions has come to  light,  which  identifies  them  as
           VT100 special characters.

           The DEC Special Character and Line Drawing Set (VT100) is indexed by an
           ASCII character in the range 96 (`) to 126 (~).  That  index  character
           is  part  of  the  definition  for  the curses ACS_ symbols.  The VT100
           special characters can be categorized in three groups:

           o   useful graphic symbols with a  standard  ACS_  symbol,  (e.g.,  the
               line-drawing symbols),

           o   possibly useful characters (these non-standard symbols),

           o   representations  of  control characters (e.g., newline and vertical
               tabulation).

           A few ACS_ symbols do not  fit  into  DEC's  VT100  scheme.   The  AT&T
           Teletype  5410v1  arrow  symbols  and ACS_BLOCK use indices outside the
           range 96 to 126.  Two of the  Teletype  symbols  use  indices  in  that
           range, with different meaning versus the VT100:

           o   ACS_BOARD corresponds to the VT100 symbol for newline

           o   ACS_LANTERN corresponds to the VT100 symbol for vertical tabulation

           AT&T defined ACS_ names for the most useful graphic symbols, as well as
           for its own.  Its header file commented:

           /*
            * Standard alternate character set.  The current ACS world is evolving,
            * so we support only a widely available subset: the line drawing characters
            * from the VT100, plus a few from the Teletype 5410v1.  Eventually there
            * may be support of more sophisticated ACS line drawing, such as that
            * in the Teletype 5410, the HP line drawing set, and the like.  There may
            * be support for some non line oriented characters as well.
            *
            * Line drawing ACS names are of the form ACS_trbl, where t is the top, r
            * is the right, b is the bottom, and l is the left.  t, r, b, and l might
            * be B (blank), S (single), D (double), or T (thick).  The subset defined
            * here only uses B and S.
            */

           Although these less-useful graphic symbols were not given  names,  they
           were  used  in  terminfo entries.  The ncurses developers invented ACS-
           prefixed names for them.

## PORTABILITY

           Applications employing ncurses extensions should condition their use on
           the visibility of the NCURSES_VERSION preprocessor macro.

           X/Open Curses Issue 4 describes these functions.  It specifies no error
           conditions for them.

           SVr4 describes a successful return value  only  as  "an  integer  value
           other than ERR".

           The  defaults specified for forms-drawing characters apply in the POSIX
           locale.

### ACS Symbols

           X/Open Curses states that the  ACS_  definitions  are  char  constants.
           Some implementations are problematic.

           o   Solaris  curses, for example, defines the ACS symbols as constants;
               others define them as elements of an array.

               SVr4 used an array, acs_map, as does ncurses.  NetBSD  curses  also
               uses  an  array,  actually  named  _acs_char,  with a "#define" for
               compatibility.

           o   HP-UX curses equates some of the  ACS_  symbols  to  the  analogous
               WACS_  symbols  as  if  the  ACS_ symbols were wide characters (see
               curs_add_wch(3x)).  The  misdefined  symbols  are  the  arrows  and
               others that are not used for line drawing.

           o   X/Open  Curses  (Issues 2  through 7) has a typographical error for
               the ACS_LANTERN symbol, equating  its  "VT100+  Character"  to  "I"
               (capital  I),  while  the  header  files  for SVr4 curses and other
               implementations use "i" (small i).

               None of the terminal descriptions on Unix platforms  use  uppercase
               I,  except  for  Solaris  (in  its  terminfo  entry  for screen(1),
               apparently based on the X/Open documentation around 1995).  On  the
               other  hand,  its gs6300 (AT&T PC6300 with EMOTS Terminal Emulator)
               description uses lowercase i.

           The displayed values of ACS_ constants depend on

           o   the ncurses ABI -- for  example,  wide-character  versus  non-wide-
               character  configurations  (the  former  is  capable  of displaying
               Unicode while the latter is not), and

           o   whether the locale uses UTF-8 encoding.

           In certain cases, the  terminal  is  unable  to  display  forms-drawing
           characters   except   by   using  UTF-8;  see  the  discussion  of  the
           NCURSES_NO_UTF8_ACS environment variable in ncurses(3x).

### Character Set

           X/Open Curses assumes that the parameter passed to  waddch  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 chtype, though the use  of
           bitwise  operators  to combine the character code with attributes and a
           color pair identifier into a chtype for passage to waddch is common.  A
           portable application uses only the macros discussed in curs_attr(3x) to
           manipulate a chtype.

           In ncurses, chtype holds an eight-bit character, but the library allows
           a  multibyte  character sequence to be passed via a succession of calls
           to waddch.  Other implementations  do  not;  a  waddch  call  transmits
           exactly  one  character,  which  may  be rendered in one or more screen
           locations depending  on  whether  it  is  printable  (see  unctrl(3x)).
           Depending  on  the  locale,  ncurses  inspects  the byte passed in each
           waddch call and checks whether the latest call  continues  a  multibyte
           character.    When  a  character  is  complete,  ncurses  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 wmove(3x) -- ncurses
           discards the incomplete character.

           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.

           o   If it can, call either waddch or wadd_wch.

           o   If it cannot, use only wadd_wch.

## HISTORY

           4BSD (1980) introduced waddch and its variants.

           SVr3  (1987) added the echochar and wechochar functions and most of the
           ACS_ constants, except for ACS_GEQUAL, ACS_LEQUAL, ACS_NEQUAL,  ACS_PI,
           ACS_S3, ACS_S7, and ACS_STERLING.

           ncurses 1.9.6 (1995) furnished the remaining ACS_ constants.

## SEE ALSO

           curs_add_wch(3x)  describes comparable functions of the ncurses library
           in its wide-character configuration (ncursesw).

           curses(3x),    curs_addchstr(3x),    curs_addstr(3x),    curs_attr(3x),
           curs_bkgd(3x),    curs_clear(3x),    curs_inch(3x),   curs_outopts(3x),
           curs_refresh(3x), curs_variables(3x), putchar(3)

    ncurses 6.5                       2025-08-16                    curs_addch(3x)