getnstr.3x (2010 09)

getnstr(3X) getnstr(3X)

(ENHANCED CURSES)

NAME

getnstr, mvgetnstr, mvwgetnstr, wgetnstr, — get a multi-byte character length limited string from the

terminal

SYNOPSIS

#include <curses.h>

int getnstr(char *str, int n);

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

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

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

DESCRIPTION

The effect of getnstr() and

wgetnstr() is as though a series of calls to getch() were made, until a

newline or carriage return is received. The resulting value is placed in the area pointed to by str. The

getnstr() and wgetnstr() functions read at most n bytes, thus preventing a possible overﬂow 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

mvgetnstr() function is identical to getnstr() except that it is as though it is a call to

move()

and then a series of calls to getch(). The mvwgetnstr() function is identical to getnstr() except

it is as though a call to

wmove() is made and then a series of calls to

wgetch().

The

getnstr(), wgetnstr(), mvgetnstr() and mvwgetnstr() 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 ﬁll 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 deﬁned.

APPLICATION USAGE

Traditional implementations often limited the number of bytes returned to 256.