curs\_instr(3X) Library calls curs\_instr(3X)

# [NAME](#NAME)

**instr**, **winstr**, **mvinstr**, **mvwinstr**, **innstr**, **winnstr**, **mvinnstr**, **mvwinnstr** - get a string from a *curses* window

# [SYNOPSIS](#SYNOPSIS)

```
#include <curses.h>
```

```
int instr(char * str);
int winstr(WINDOW * win, char * str);
int mvinstr(int y, int x, char * str);
int mvwinstr(WINDOW * win, int y, int x, char * str);
```

```
int innstr(char * str, int n);
int winnstr(WINDOW * win, char * str, int n);
int mvinnstr(int y, int x, char * str, int n);
int mvwinnstr(WINDOW * win, int y, int x, char * str, int n);
```

# [DESCRIPTION](#DESCRIPTION)

**winstr** extracts a string from a *curses* window *win*, starting at the cursor and stopping at the end of the line, and stores it in *str*, terminating it with a null character and omitting any attributes and color pair identifier that *curses* associates with each character. **winnstr** does the same, but copies at most *n* characters from *win*. A negative *n* implies no limit; **winnstr** then works like **winstr**. [**ncurses**(3X)](/man/os/ncurses/ncurses.3X) describes the variants of these functions.

# [RETURN VALUE](#RETURN_VALUE)

These functions return the count of characters copied from *win* to *str* (not including the null terminator), or **ERR** upon failure.

In *ncurses*, these functions fail if

- the *curses* screen has not been initialized,
- (for functions taking a *WINDOW* pointer argument) *win* is a null pointer, or
- *str* is a null pointer.

Functions prefixed with “mv” first perform cursor movement and fail if the position (*y*, *x*) is outside the window boundaries.

# [NOTES](#NOTES)

All of these functions except **winnstr** may be implemented as macros.

Reading a line that overflows the array pointed to by *str* with and its variants causes undefined results. Instead, use the *n*-infixed functions with a positive *n* argument no larger than the size of the buffer backing *str*.

# [EXTENSIONS](#EXTENSIONS)

**innstr**, **winnstr**, **mvinnstr**, and **mvwinnstr**'s acceptance of negative *n* values is an *ncurses* extension.

# [PORTABILITY](#PORTABILITY)

Applications employing *ncurses* extensions should condition their use on the visibility of the **NCURSES\_VERSION** preprocessor macro.

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them.

X/Open Curses Issues 4 and 7 both state that *instr*, *winstr*, *mvinstr*, and *mvwinstr* return *OK* rather than a character count. This is likely an erratum.

- SVr3.1 and SVr4 implemented *winstr* as a wrapper around *winnstr*, returning the latter's return value. X/Open Curses's specification thus may have been an editorial solecism copied from System V's documentation (see below) by X/Open, rather than an intentional change.
- *ncurses* retains compatibility with System V *curses* behavior.

SVr4 describes a successful return value only as “an integer value other than *ERR*”.

SVr4 does not document whether *n* counts the null terminator that these functions write to *str*.

# [HISTORY](#HISTORY)

SVr3.1 (1987) introduced these functions.

# [SEE ALSO](#SEE_ALSO)

[**curs\_inwstr**(3X)](/man/os/ncurses/curs_inwstr.3X) describes comparable functions of the *ncurses* library in its wide-character configuration (*ncursesw*).

[**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_inch**(3X)](/man/os/ncurses/curs_inch.3X), [**curs\_inchstr**(3X)](/man/os/ncurses/curs_inchstr.3X)

2025-10-20 ncurses 6.6

---

Document: curs_instr(3x) from ncurses 6.6.20260926-r0 (Chainguard OS)
Source: https://github.com/ThomasDickey/ncurses-snapshots