man7.org > Linux > man-pages

Linux/UNIX system programming training

curs_addchstr(3x) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | PORTABILITY | HISTORY | SEE ALSO | COLOPHON 

curs_addchstr(3X)             Library calls             curs_addchstr(3X)

NAME         top

       addchstr, waddchstr, mvaddchstr, mvwaddchstr, addchnstr,
       waddchnstr, mvaddchnstr, mvwaddchnstr - add a curses character
       string to a window

SYNOPSIS         top

       #include <curses.h>

       int addchstr(const chtype * chstr);
       int waddchstr(WINDOW * win, const chtype * chstr);
       int mvaddchstr(int y, int x, const chtype * chstr);
       int mvwaddchstr(WINDOW * win, int y, int x,
             const chtype * chstr);

       int addchnstr(const chtype * chstr, int n);
       int waddchnstr(WINDOW * win, const chtype * chstr, int n);
       int mvaddchnstr(int y, int x, const chtype * chstr, int n);
       int mvwaddchnstr(WINDOW * win, int y, int x,
             const chtype * chstr, int n);

DESCRIPTION         top

       waddchstr copies the string of curses characters chstr to the
       window win.  A null curses character terminates the string.
       waddchnstr does the same, but copies at most n characters, or as
       many as possible if n is -1.  ncurses(3X) describes the variants
       of these functions.

       Because these functions do not call waddch(3X) internally, they
       are faster than waddstr(3X) and waddnstr(3X).  On the other hand,
       they

       •   do not treat the backspace, carriage return, or line feed
           characters specially;

       •   do not represent unprintable characters with unctrl(3X);

       •   do not update the cursor position to follow the last character
           written; and

       •   truncate the string at the window's right margin, rather than
           wrapping it to the next line and potentially scrolling.

RETURN VALUE         top

       These functions return OK on success and ERR on failure.

       In ncurses, these functions fail if

       •   the curses screen has not been initialized,

       •   chstr is a null pointer, or

       •   (for functions taking a WINDOW pointer argument) win is a null
           pointer.

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

NOTES         top

       All of these functions except waddchnstr may be implemented as
       macros.

PORTABILITY         top

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

HISTORY         top

       SVr3.1 (1987) introduced these functions.

SEE ALSO         top

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

       curses(3X), curs_addch(3X), curs_addstr(3X)

COLOPHON         top

       This page is part of the ncurses (new curses) project.
       Information about the project can be found at 
       ⟨https://invisible-island.net/ncurses/ncurses.html⟩.  If you have a
       bug report for this manual page, send it to bug-ncurses@gnu.org.
       This page was obtained from the tarball ncurses-6.6.tar.gz fetched
       from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16.  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for the
       page, or you have corrections or improvements to the information
       in this COLOPHON (which is not part of the original manual page),
       send a mail to man-pages@man7.org

ncurses @NCURSES_MAJOR@.@NCU... 2025-08-16              curs_addchstr(3X)

HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface.

For details of in-depth Linux/UNIX system programming training courses that I teach, look here.

Hosting by jambit GmbH.

Cover of TLPI