getnstr(3curses)

getnstr -- get a multi-byte character string from the terminal

Synopsis

cc [options] file -lcurses

#include <curses.h>

int getnstr(char *str, int n);

int getstr(char *str);

int mvgetnstr(int y, int x, char *str, int n);

int mvgetstr(int y, int x, char *str);

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

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

int wgetnstr(WINDOW *win, char *str, int n);

int wgetstr(WINDOW *win, char *str);

Description

The effect of getstr(3curses) is as though a series of calls to getch(3curses) were made, until a newline, carriage return or end-of-file is received. The resulting value is placed in the area pointed to by str. The string is then terminated with a null byte. The getnstr(3curses), mvgetnstr(3curses), mvwgetnstr(3curses) and wgetnstr(3curses) functions read at most n bytes, thus preventing a possible overflow of the input buffer. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on).

The mvgetstr(3curses) function is identical to getstr(3curses) except that it is as though it is a call to move(3curses) and then a series of calls to getch(3curses).

The mvwgetstr(3curses) function is identical to getstr(3curses) except it is as though a call to wmove(3curses) is made and then a series of calls to wgetch(3curses).

The mvgetnstr(3curses) function is identical to getnstr(3curses) except that it is as though it is a call to move(3curses) and then a series of calls to getch(3curses).

The mvwgetnstr(3curses) function is identical to getnstr(3curses) except it is as though a call to wmove(3curses) is made and then a series of calls to wgetch(3curses).

The getnstr(3curses), wgetnstr(3curses), mvgetnstr(3curses) and mvwgetnstr(3curses) functions will only return the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails.

Return value

Upon successful completion, these functions return OK. Otherwise, they return ERR.

Errors

No errors are defined.

Usage

Reading a line that overflows the array pointed to by str with getstr(3curses), mvgetstr(3curses), mvwgetstr(3curses) or wgetstr(3curses) causes undefined results. The use of getnstr(3curses), mvgetnstr(3curses), mvwgetnstr(3curses) or wgetnstr(3curses), respectively, is recommended.

Standards Conformance

The Single UNIX Specification, Version 2; The Open Group.

References

``Input Processing'', beep(3curses), getch(3curses), curses(4)