# curs_addch 3x 2025-04-05 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.)   See  curs_attr(3x)  for values of predefined
           constants that can be usefully "or"ed  with  characters.   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  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.

           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.

           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, it  is  drawn  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.

### 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.   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
           bit  operations  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-04-05                    curs_addch(3x)