getnstr, getstr, mvgetnstr, mvgetstr, mvwgetnstr, mvwgetstr, wgetnstr, or wgetstr Subroutine

Purpose

Gets a multi-byte character string from the terminal.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>

int getnstr(char  *str,
int n);

int getstr(char *str);

int mvgetnstr(int y,
int x,
char *st,
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 the getstr subroutine is as though a series of calls to the getch subroutine was made, until a newline subroutine, 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, mvgetnstr, mvwgetnstr, and wgetnstr subroutines 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 subroutines is identical to the getstr subroutine except that it is as though it is a call to the move subroutine and then a series of calls to the getch subroutine. The mvwgetstr subroutine is identical to the getstr subroutine except that it is as though it is a call to the wmove subroutine and then a series of calls to the wgetch subroutine.

The mvgetnstr subroutines is identical to the getstr subroutine except that it is as though it is a call to the move subroutine and then a series of calls to the getch subroutine. The mvwgetnstr subroutine is identical to the getstr subroutine except that it is as though it is a call to the wmove subroutine and then a series of calls to the wgetch subroutine.

The getstr, wgetstr, mvgetstr, and mvwgetstr subroutines 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 subroutines fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails.

Parameters

Item Description
n Specifies the upper boundary on the number of bytes to read.
x Holds the column coordinate of the logical cursor.
y Holds the line or row coordinate of the logical cursor.
*str Identifies where to store the string.
*win Identifies the window to get the string from and echo it into.

Return Values

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

Examples

  1. To get a string, store it in the user-defined variable my_string, and echo it into the stdscr, enter: 
    char *my_string;
getstr(my_string);
  2. To get a string, echo it into the user-defined window my_window, and store it in the user-defined variable my_string, enter: 
    WINDOW *my_window;
char *my_string;
wgetstr(my_window, my_string);
  3. To get a string in the stdscr at coordinates y=20, x=30, and store it in the user-defined variable my_string, enter: 
    char *string;
mvgetstr(20, 30, string);
  4. To get a string in the user-defined window my_window at coordinates y=20, x=30, and store it in the user-defined variable my_string, enter: 
    WINDOW *my_window;
char *my_string;
mvwgetstr(my_window, 20, 30, my_string);