---
name: "curs_addch"
section: "3x"
platform: "macos"
package: "ncurses"
version: "79"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/curs_addch/3x"
---

# curs\_addch(3x)

add a character (with attributes) to a curses window, then advance the cursor

## NAME

**addch**, **waddch**, **mvaddch**, **mvwaddch**, **echochar**, **wechochar** - add a character (with attributes) to a **curses** window, then 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);**\

## DESCRIPTION

### Adding characters

The **addch**, **waddch**, **mvaddch** and **mvwaddch** routines put the character *ch* into the given window at its current window position, which is then advanced.  They are analogous to **putchar** in [**stdio**(3)](/stdio/3.md). 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, and if **scrollok** is enabled, the scrolling region is scrolled up one line.

- •

  If **scrollok** 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

If *ch* is a tab, newline, carriage return 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.

- •

  Carriage return moves the cursor to the window left margin on the current line.

- •

  Newline does a **clrtoeol**, 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 **TABSIZE** variable.

If *ch* is any other control character, it is drawn in **^***X* notation.  Calling **winch** after adding a control character does not return the character itself, but instead returns the ^-representation of the control character.

Video attributes can be combined with a character argument passed to **addch** or related functions by logical-ORing them into the character. (Thus, text, including attributes, can be copied from one place to another using **inch** and **addch**.)  See the **curs\_attr**(3X) page for values of predefined video attribute constants that can be usefully OR'ed into characters.

### Echoing characters

The **echochar** and **wechochar** routines are equivalent to a call to **addch** followed by a call to **refresh**, or a call to **waddch** followed by a call to **wrefresh**.  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.

### Line Graphics

The following variables may be used to add line drawing characters to the screen with routines of the **addch** family.  The default character listed below is used if the **acsc** capability does not define a terminal-specific replacement for it. The names are taken from VT100 nomenclature.

| | | |
| --- | --- | --- |
| *Name* | *Default* | *Description* |
|
| 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 |

## RETURN VALUE

All routines return the integer **ERR** upon failure and **OK** on success (the SVr4 manuals specify only "an integer value other than **ERR**") upon successful completion, unless otherwise noted in the preceding routine descriptions.

Functions with a "mv" prefix first perform a cursor movement using **wmove**, and return an error if the position is outside the window, or if the window pointer is null.

## NOTES

Note that **addch**, **mvaddch**, **mvwaddch**, and **echochar** may be macros.

## 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.

X/Open Curses states that the *ACS\_* definitions are **char** constants. For the wide-character implementation (see **curs\_add\_wch**), there are analogous *WACS\_* definitions which are **cchar\_t** constants.

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 **acsc** 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 **ncurses**(3X).

The **TABSIZE** variable is implemented in some versions of curses, but is not part of X/Open curses.

If *ch* 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.

## SEE ALSO

**curses**(3X), **curs\_attr**(3X), **curs\_clear**(3X), **curs\_inch**(3X), **curs\_outopts**(3X), **curs\_refresh**(3X), **curs\_variables**(3X), [**putc**(3)](/putc/3.md).

Comparable functions in the wide-character (ncursesw) library are described in **curs\_add\_wch**(3X).