ncurses 4.1
[ncurses.git] / man / curs_instr.3x
1 .\" $Id: curs_instr.3x,v 1.7 1997/03/15 23:25:24 tom Exp $
2 .TH curs_instr 3X ""
3 .SH NAME
4 \fBinstr\fR, \fBinnstr\fR, \fBwinstr\fR, \fBwinnstr\fR,
5 \fBmvinstr\fR, \fBmvinnstr\fR, \fBmvwinstr\fR, \fBmvwinnstr\fR - get a string
6 of characters from a \fBcurses\fR window
7 .SH SYNOPSIS
8 \fB#include <curses.h>\fR
9
10 \fBint instr(char *str);\fR
11 .br
12 \fBint innstr(char *str, int n);\fR
13 .br
14 \fBint winstr(WINDOW *win, char *str);\fR
15 .br
16 \fBint winnstr(WINDOW *win, char *str, int n);\fR
17 .br
18 \fBint mvinstr(int y, int x, char *str);\fR
19 .br
20 \fBint mvinnstr(int y, int x, char *str, int n);\fR
21 .br
22 \fBint mvwinstr(WINDOW *win, int y, int x, char *str);\fR
23 .br
24 \fBint mvwinnstr(WINDOW *win, int y, int x, char *str, int n);\fR
25 .br
26 .SH DESCRIPTION
27 These routines return a string of characters in \fIstr\fR, extracted starting
28 at the current cursor position in the named window.
29 Attributes are stripped from the characters.  The four
30 functions with \fIn\fR as the last argument return a leading substring at most
31 \fIn\fR characters long (exclusive of the trailing NUL).
32 .SH RETURN VALUE
33 All of the functions return \fBERR\fR upon failure,
34 or the number of characters actually read into the string.
35 .SH NOTES
36 Note that all routines except \fBwinnstr\fR may be macros.
37 .SH PORTABILITY
38 The XSI Curses
39 error conditions \fBEILSEQ\fR and \fBEILOVERFLOW\fR associated with
40 extended-level conformance are not yet detected (this implementation does not
41 yet support XPG4 multi-byte characters).
42 SVr4 does not
43 document whether a length limit includes or excludes the trailing NUL.
44 .PP
45 The ncurses library extends the XSI description by allowing a negative
46 value for \fIn\fR.
47 In this case, the functions return the string ending at the right margin.
48 .SH SEE ALSO
49 \fBcurses\fR(3X).
50 .\"#
51 .\"# The following sets edit modes for GNU EMACS
52 .\"# Local Variables:
53 .\"# mode:nroff
54 .\"# fill-column:79
55 .\"# End:
56