innstr.3x (2010 09)

innstr(3X) innstr(3X)

(ENHANCED CURSES)

NAME

innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr — input a multi-byte character

string from a window

SYNOPSIS

#include <curses.h>

int innstr(char *str, int n);

int instr(char *str);

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

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

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

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

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

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

DESCRIPTION

These functions place a string of characters from the current or speciﬁed window into the array pointed to

by str, starting at the current or speciﬁed position and ending at the end of the line.

The

innstr(), mvinnstr(), mvwinnstr() and winnstr() functions store at most n bytes in the

string pointed to by str.

The

innstr(), mvinnstr(), mvwinnstr() and winnstr() functions will only store the entire

multi-byte sequence associated with a character. If the array is large enough to contain at least one char-

acter the array is ﬁlled with complete characters. If the array is not large enough to contain any complete

characters, the function fails.

RETURN VALUE

Upon successful completion,

instr(), mvinstr(), mvwinstr() and winstr() return OK.

Upon successful completion,

innstr(), mvinnstr(), mvwinnstr() and winnstr() return the

number of characters actually read into the string.

Otherwise, all these functions return ERR.

ERRORS

No errors are deﬁned.

APPLICATION USAGE

Since multi-byte characters may be processed, there might not be a one-to-one correspondence between

the number of column positions on the screen and the number of bytes returned.

These functions do not return rendition information.

Reading a line that overﬂows the array pointed to by str with

instr(), mvinstr(), mvwinstr() or

winstr() causes undeﬁned results. The use of innstr(), mvinnstr(), mvwinnstr() or

winnstr(), respectively, is recommended.