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

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

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 wgetnsrt 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

n
x
y
*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

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);
```
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);
```
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);
```
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);
```

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The beep subroutine, getch subroutine, keypad subroutine, nodelay subroutine, wgetch subroutine.

Curses Overview for Programming, List of Curses Subroutines, Manipulating Characters with Curses in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.