---
name: "instr"
section: "3ncurses"
platform: "linux"
package: "ncurses-doc"
version: "6.5+20250216-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/instr/3ncurses"
---

# instr(3ncurses)

get a string from a curses window

## NAME

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

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

**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(3NCURSES) describes the variants of these functions.**

## RETURN VALUE

**These functions return the count of characters copied from** *win* **to** *str*, **or** **ERR** **upon failure.**

**In** *ncurses*, **they return** **ERR** **if**

- •

  *win* **is** *NULL* **or**

- •

  *str* **is** *NULL*.

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

## NOTES

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

**Reading a line that overflows the array pointed to by** *str* **with** **instr**, **winstr**, **mvinstr**, **or** **mvwinstr** **causes undefined results.** **Use of** **innstr**, **winnstr**, **mvinnstr**, **and** **mvwinnstr** **is recommended instead.**

## EXTENSIONS

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

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

**SVr3.1 (1987)** **introduced these functions.** *winstr*, *winnstr*, **and their variants.**

## SEE ALSO

**inwstr(3NCURSES) describes comparable functions of the** *ncurses* **library in its wide-character configuration** (*ncursesw*).

**ncurses(3NCURSES),** **inch(3NCURSES),** **inchstr(3NCURSES)**