|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXTENSIONS | PORTABILITY | HISTORY | SEE ALSO | COLOPHON |
|
|
|
curs_instr(3X) Library calls curs_instr(3X)
instr, winstr, mvinstr, mvwinstr, innstr, winnstr, mvinnstr,
mvwinnstr - get a string from a curses window
#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);
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) describes the variants of these functions.
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.
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.
innstr, winnstr, mvinnstr, and mvwinnstr's acceptance of negative
n values is an ncurses extension.
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.
SVr3.1 (1987) introduced these functions.
curs_inwstr(3X) describes comparable functions of the ncurses
library in its wide-character configuration (ncursesw).
curses(3X), curs_inch(3X), curs_inchstr(3X)
This page is part of the ncurses (new curses) project.
Information about the project can be found at
⟨https://invisible-island.net/ncurses/ncurses.html⟩. If you have a
bug report for this manual page, send it to bug-ncurses@gnu.org.
This page was obtained from the tarball ncurses-6.6.tar.gz fetched
from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16. If you
discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information
in this COLOPHON (which is not part of the original manual page),
send a mail to man-pages@man7.org
ncurses @NCURSES_MAJOR@.@NCU... 2025-10-20 curs_instr(3X)
|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|