innstr(3curses)

innstr -- input a multi-byte character string from a window

Synopsis

cc [options] file -lcurses

#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 specified window into the array pointed to by str, starting at the current or specified position and ending at the end of the line.

The innstr(3curses), mvinnstr(3curses), mvwinnstr(3curses) and winnstr(3curses) functions store at most n bytes in the string pointed to by str.

The innstr(3curses), mvinnstr(3curses), mvwinnstr(3curses) and winnstr(3curses) functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails.

Return value

Upon successful completion, instr(3curses), mvinstr(3curses), mvwinstr(3curses) and winstr(3curses) return OK.

Upon successful completion, innstr(3curses), mvinnstr(3curses), mvwinnstr(3curses) and winnstr(3curses) return the number of characters actually read into the string.

Otherwise, all these functions return ERR.

Errors

No errors are defined.

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 overflows the array pointed to by str with instr(3curses), mvinstr(3curses), mvwinstr(3curses) or winstr(3curses) causes undefined results. The use of innstr(3curses), mvinnstr(3curses), mvwinnstr(3curses) or winnstr(3curses), respectively, is recommended.

Standards Conformance

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

References

curses(4)