# curs_inchstr 3x 2025-02-15 ncurses 6.5 Library calls

    curs_inchstr(3x)                 Library calls                curs_inchstr(3x)

## NAME

           inchstr,   inchnstr,   winchstr,   winchnstr,   mvinchstr,  mvinchnstr,
           mvwinchstr, mvwinchnstr - get a curses character string from a window

## SYNOPSIS

           #include <curses.h>

           int inchstr(chtype *chstr);
           int inchnstr(chtype *chstr, int n);
           int winchstr(WINDOW *win, chtype *chstr);
           int winchnstr(WINDOW *win, chtype *chstr, int n);

           int mvinchstr(int y, int x, chtype *chstr);
           int mvinchnstr(int y, int x, chtype *chstr, int n);
           int mvwinchstr(WINDOW *win, int y, int x, chtype *chstr);
           int mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n);

## DESCRIPTION

           These routines return a NULL-terminated  array  of  chtype  quantities,
           starting  at the current cursor position in the named window and ending
           at the right margin of the window.

           The four functions with n  as  the  last  argument,  return  a  leading
           substring  at  most  n  characters  long  (exclusive  of  the  trailing
           (chtype)0).  Transfer stops at the end of the current line, or  when  n
           characters have been stored at the location referenced by chstr.

           Constants  defined in <curses.h> can be used with the & (logical "and")
           operator to extract the character  or  the  attribute  alone  from  any
           position in the chstr [see curs_inch(3x)].

## RETURN VALUE

           All  routines  return the integer ERR upon failure and an integer value
           other than ERR upon successful completion  (the  number  of  characters
           retrieved, exclusive of the trailing 0).

           X/Open Curses defines no error conditions.  This implementation returns
           ERR

           o   if the win parameter is null or

           o   if the chstr parameter is null.

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

## NOTES

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

           Reading  a  line  that  overflows  the  array  pointed to by chstr with
           inchstr, mvinchstr, mvwinchstr or winchstr  causes  undefined  results.
           Therefore,  the  use of inchnstr, mvinchnstr, mvwinchnstr, or winchnstr
           is recommended.

## PORTABILITY

           X/Open Curses Issue 4 describes these functions.  It specifies no error
           conditions  for  them.   It  characterizes  the strings stored by these
           functions as containing "at most n elements" from a  window,  but  does
           not  specify  whether  the  string  stored  by these functions is null-
           terminated.

           SVr4 does not document whether it null-terminates the string it  stores
           in  chstr,  and  does  not  document  whether a trailing null character
           counts toward the length limit n.

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

## SEE ALSO

           curses(3x), curs_inch(3x), curs_inwstr(3x), curs_in_wchstr(3x)

    ncurses 6.5                       2025-02-15                  curs_inchstr(3x)