CURSES_INCH(3)

CURSES_INCH(3) | Library Functions Manual | CURSES_INCH(3)

# NAME

`curses_inch`, `inch`, `winch`, `inchnstr`, `mvinchnstr`, `winchnstr`, `mvwinchnstr`, `inchstr`, `mvinchstr`, `winchstr`, `mvwinchstr`, `innstr`, `winnstr`, `mvinnstr`, `mvwinnstr`, `instr`, `winstr`, `mvinstr`, `mvwinstr` —
curses read screen contents routines

# LIBRARY

Curses Library (libcurses, -lcurses)

# SYNOPSIS

`#include <curses.h>`

chtype
`inch`(void);

chtype
`winch`(WINDOW *win);

int
`inchnstr`(chtype *chars, int n);

int
`mvinchnstr`(int y, int x, chtype *chstr, int n);

int
`winchnstr`(WINDOW *win, chtype *chars, int n);

int
`mvwinchnstr`(WINDOW *win, int y, int x, chtype *chstr, int n);

int
`inchstr`(chtype *chars);

int
`mvinchstr`(int y, int x, chtype *chstr);

int
`winchstr`(WINDOW *win, chtype *chars);

int

mvwinchstr WINDOW *win int y int x chtype *chstr

int
`innstr`(char *str, int n);

int
`winnstr`(WINDOW *win, char *str, int n);

int
`mvinnstr`(int y, int x, char *str, int n);

int
`mvwinnstr`(WINDOW *win, int y, int x, char *str, int n);

int
`instr`(char *str);

int
`winstr`(WINDOW *win, char *str);

int
`mvinstr`(int y, int x, char *str);

int
`mvwinstr`(WINDOW *win, int y, int x, char *str);

# DESCRIPTION

These functions read the contents of `stdscr` or of the specified window.

The `inch`() function returns the character that is displayed on `stdscr` at the current cursor position.

The `winch`() function is the same as the `inch`() function, excepting that the character is read from window specified by win.

The `inchnstr`() function fills an array of chtype with characters read from `stdscr`, the characters are read starting from the current cursor position and continuing until either n - 1 characters are read or the right hand side of the screen is reached. The resulting character array will be `NULL` terminated.

The `winchnstr`() function is the same as `inchnstr`() excepting that the characters are read from the window specified by win.

The `inchstr`() and `winchstr`() functions are the same as the `inchnstr`() and `winchnstr`() functions, respectively, excepting that they do not limit the number of characters read. The characters returned are those from the current starting position to the right hand side of the screen. The use of `inchstr`() and `winchstr`() is not recommended as the character buffer can be overflowed.

The `innstr`() function is similar to the `inchstr`() function, excepting that the array of characters returned is stripped of all the curses attributes making it a plain character string.

The `mvinchstr`(), `mvinchnstr`(), `mvwinchstr`(), and `mvwinchnstr`() functions are the same as the `inchstr`(), `inchnstr`(), `winchstr`(), and `winchstr`() functions, respectively, except that `wmove`() is called to move the cursor to the position specified by y, x before the output is printed on the window. Likewise, the `mvinstr`(), `mvinnstr`(), `mvwinstr`(), and `mvwinnstr`() functions are the same as the `instr`(), `innstr`(), `winstr`(), and `winstr`() functions, respectively, except that `wmove`() is called to move the cursor to the position specified by y, x before the output is printed on the window.

The `winnstr`() function is the same as the `innstr`() function, excepting that characters are read from the window specified by win.

The `instr`() and `winstr`() functions are the same as the `innstr`() and `winnstr`() functions, respectively, excepting that there are no limits placed on the size of the returned string, which may cause buffer overflows. For this reason, the use of `instr`() and `winstr`() is not recommended.

# RETURN VALUES

If the calls `innstr`(), `mvinnstr`(), `mvwinnstr`(), and `winnstr`() succeed then they will return the number of characters actually read. Functions returning pointers will return `NULL` if an error is detected. The functions that return an int will return one of the following values:

`OK`
  The function completed successfully.
`ERR`
  An error occurred in the function.

# SEE ALSO

curses_addch(3), curses_addstr(3), curses_attributes(3), curses_insch(3)

# STANDARDS

The NetBSD Curses library complies with the X/Open Curses specification, part of the Single Unix Specification.

# NOTES

The `inchnstr`() and `innstr`() function read at most n - 1 characters from the screen so as to leave room for `NULL` termination. The X/Open specification is unclear as to whether or not this is the correct behaviour.

# HISTORY

The Curses package appeared in 4.0BSD.

October 25, 2018 | NetBSD 10.1