Debian Codegraph @

upstream/debian-unstable/man3/inchstr.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_inchstr.3x,v 1.65 2025/10/21 00:05:02 tom Exp $
31 .TH inchstr 3NCURSES 2025-10-20 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%inchstr\fP,
49 \fB\%inchnstr\fP,
50 \fB\%winchstr\fP,
51 \fB\%winchnstr\fP,
52 \fB\%mvinchstr\fP,
53 \fB\%mvinchnstr\fP,
54 \fB\%mvwinchstr\fP,
55 \fB\%mvwinchnstr\fP \-
56 get a \fIcurses\fR character string from a window
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint inchstr(chtype * \fIchstr\fP);
62 \fBint inchnstr(chtype * \fIchstr\fP, int \fIn\fP);
63 \fBint winchstr(WINDOW * \fIwin\fP, chtype * \fIchstr\fP);
64 \fBint winchnstr(WINDOW * \fIwin\fP, chtype * \fIchstr\fP, int \fIn\fP);
65 .PP
66 \fBint mvinchstr(int \fIy\fP, int \fIx\fP, chtype * \fIchstr\fP);
67 \fBint mvinchnstr(int \fIy\fP, int \fIx\fP, chtype * \fIchstr\fP, int \fIn\fP);
68 \fBint mvwinchstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, chtype * \fIchstr\fP);
69 \fBint mvwinchnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, chtype * \fIchstr\fP, int \fIn\fP);
70 .fi
71 .SH DESCRIPTION
72 .B \%winchstr
73 extracts a
74 .I curses
75 character string from a
76 .I curses
77 window
78 .IR win ","
79 starting at the cursor and stopping at the end of the line,
80 and stores it in
81 .IR chstr ","
82 terminating it with a null
83 .I curses
84 character.
85 .B \%winchnstr
86 does the same,
87 but copies at most
88 .I n
89 .I curses
90 characters from
91 .IR win "."
92 A negative
93 .I n
94 implies no limit;
95 .B \%winchnstr
96 then works like
97 .BR \%winchstr "."
98 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
99 .SH RETURN VALUE
100 These functions return
101 .B OK
102 on success and
103 .B ERR
104 on failure.
105 .PP
106 In
107 .IR \%ncurses ","
108 these functions fail if
109 .bP
110 the
111 .I curses
112 screen has not been initialized,
113 .bP
114 (for functions taking a
115 .I \%WINDOW
116 pointer argument)
117 .I win
118 is a null pointer,
119 or
120 .bP
121 .I chstr
122 is a null pointer.
123 .PP
124 Functions prefixed with \*(``mv\*('' first perform cursor movement and
125 fail if the position
126 .RI ( y ,
127 .IR x )
128 is outside the window boundaries.
129 .SH NOTES
130 All of these functions except
131 .B \%winchnstr
132 may be implemented as macros.
133 .PP
134 Reading a line that overflows the array pointed to by
135 .I chstr
136 and its variants causes undefined results.
137 Instead,
138 use the
139 .IR n -infixed
140 functions with a positive
141 .I n
142 argument no larger than the size of the buffer backing
143 .IR chstr "."
144 .SH EXTENSIONS
145 .BR \%inchnstr ","
146 .BR \%winchnstr ","
147 .BR \%mvinchnstr ","
148 and
149 .BR \%mvwinchnstr "'s"
150 acceptance of negative
151 .I n
152 values is an
153 .I \%ncurses
154 extension.
155 .SH PORTABILITY
156 Applications employing
157 .I \%ncurses
158 extensions should condition their use on the visibility of the
159 .B \%NCURSES_VERSION
160 preprocessor macro.
161 .PP
162 X/Open Curses Issue\ 4 describes these functions.
163 It specifies no error conditions for them.
164 It characterizes the strings stored by these functions as containing
165 \*(``at most
166 .I n
167 elements\*('' from a window,
168 .\" X/Open Issue 4, Version 2, p. 113, PDF p. 133
169 .\" Issue 7 doesn't change this wording at all.
170 but does not specify whether the string stored by these functions is
171 null-terminated.
172 .PP
173 SVr4 does not document whether it null-terminates the
174 .I curses
175 character string it stores
176 in
177 .IR chstr ","
178 and does not document whether a trailing null
179 .I curses
180 character counts
181 toward the length limit
182 .IR n "."
183 .PP
184 SVr4 describes a successful return value only as
185 \*(``an integer value other than
186 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 503
187 .SH HISTORY
188 SVr3.1 (1987)
189 introduced these functions.
190 .SH SEE ALSO
191 \fB\%in_wchstr\fP(3NCURSES) describes comparable functions of the
192 .I \%ncurses
193 library in its wide-character configuration
194 .RI \%( ncursesw ).
195 .PP
196 \fB\%ncurses\fP(3NCURSES),
197 \fB\%inch\fP(3NCURSES),
198 \fB\%inwstr\fP(3NCURSES)