getn_wstr(3curses)

getn_wstr -- get an array of wide characters and function key codes from a terminal

Synopsis

cc [options] file -lcurses

#include <curses.h>

int getn_wstr(wchar_t *wstr, int n);

int get_wstr(wchar_t *wstr);

int mvgetn_wstr(int y, int x, wchar_t *wstr, int n);

int mvget_wstr(int y, int x, wchar_t *wstr);

int mvwgetn_wstr(WINDOW *win, int y, int x, wchar_t *wstr, int n);

int mvwget_wstr(WINDOW *win, int y, int x, wchar_t *wstr);

int wgetn_wstr(WINDOW *win, wchar_t *wstr, int n);

int wget_wstr(WINDOW *win, wchar_t *wstr);

Description

The effect of get_wstr(3curses) is as though a series of calls to get_wch(3curses) were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in <wchar.h>. A newline or end-of-line is represented as its wchar_t value. In all instances, the end of the string is terminated by a null wchar_t. The resulting values are placed in the area pointed to by wstr.

The user's erase and kill characters are interpreted and affect the sequence of characters returned.

The effect of wget_wstr(3curses) is as though a series of calls to wget_wch(3curses) were made.

The effect of mvget_wstr(3curses) is as though a call to move(3curses) and then a series of calls to get_wch(3curses) were made.

The effect of mvwget_wstr(3curses) is as though a call to wmove(3curses) and then a series of calls to wget_wch(3curses) were made.

The effect of mvgetn_wstr(3curses) is as though a call to move(3curses) and then a series of calls to get_wch(3curses) were made.

The effect of mvwgetn_wstr(3curses) is as though a call to wmove(3curses) and then a series of calls to wget_wch(3curses) were made.

The getn_wstr(3curses), mvgetn_wstr(3curses), mvwgetn_wstr(3curses) and wgetn_wstr(3curses) functions read at most n characters, letting the application prevent overflow of the input buffer.

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 wstr with get_wstr(3curses), mvget_wstr(3curses), mvwget_wstr(3curses) or wget_wstr(3curses) causes undefined results. The use of getn_wstr(3curses), mvgetn_wstr(3curses), mvwgetn_wstr(3curses) or wgetn_wstr(3curses), respectively, is recommended.

These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid wchar_t value.

Standards Conformance

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

References

get_wch(3curses), getstr(3curses), curses(4), wchar(5), termio(7), ``General terminal interface'' in Programming with system calls and libraries