Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-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_insstr.3x,v 1.72 2025/10/21 00:11:17 tom Exp $
31 .TH insstr 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\%insstr\fP,
49 \fB\%winsstr\fP,
50 \fB\%mvinsstr\fP,
51 \fB\%mvinsnstr\fP,
52 \fB\%insnstr\fP,
53 \fB\%winsnstr\fP,
54 \fB\%mvwinsstr\fP,
55 \fB\%mvwinsnstr\fP \-
56 insert a string in a \fIcurses\fR window
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint insstr(const char * \fIstr\fP);
62 \fBint winsstr(WINDOW * \fIwin\fP, const char * \fIstr\fP);
63 \fBint mvinsstr(int \fIy\fP, int \fIx\fP, const char * \fIstr\fP);
64 \fBint mvwinsstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const char * \fIstr\fP);
65 .PP
66 \fBint insnstr(const char * \fIstr\fP, int \fIn\fP);
67 \fBint winsnstr(WINDOW * \fIwin\fP, const char * \fIstr\fP, int \fIn\fP);
68 \fBint mvinsnstr(int \fIy\fP, int \fIx\fP, const char * \fIstr\fP, int \fIn\fP);
69 \fBint mvwinsnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const char * \fIstr\fP, int \fIn\fP);
70 .fi
71 .SH DESCRIPTION
72 .B \%winsstr
73 inserts a string
74 .I str
75 before the character at the cursor in window
76 .I win
77 as if by calling \fBwinsch\fP(3NCURSES) for each
78 .I char
79 in
80 .IR str "."
81 No line wrapping is performed.
82 Characters to the right of the cursor are shifted right;
83 those at the right edge of the window may be lost.
84 .B \%winsstr
85 stops inserting if it would have to wrap to the next line to write the
86 next
87 .I \%char
88 in
89 .IR str "."
90 The cursor position does not change
91 (after moving to
92 .RI ( y ,
93 .IR x "),"
94 if specified).
95 .B \%insnstr
96 does the same,
97 but inserts at most
98 .I n
99 characters,
100 or as many as possible
101 (up to the end of the line)
102 if
103 .I n
104 is negative.
105 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
106 .SH RETURN VALUE
107 These functions return
108 .B OK
109 on success and
110 .B ERR
111 on failure.
112 .PP
113 In
114 .IR \%ncurses ","
115 they return
116 .B ERR
117 if
118 .bP
119 .I win
120 is
121 .IR NULL ","
122 .bP
123 .I str
124 is
125 .IR NULL ","
126 or
127 .bP
128 an internal \fBwinsch\fP(3NCURSES) call returns
129 .BR ERR "."
130 .PP
131 Functions prefixed with \*(``mv\*('' first perform cursor movement and
132 fail if the position
133 .RI ( y ,
134 .IR x )
135 is outside the window boundaries.
136 .SH NOTES
137 All of these functions except
138 .B \%winsnstr
139 may be implemented as macros.
140 .SH EXTENSIONS
141 .BR \%insnstr ","
142 .BR \%winsnstr ","
143 .BR \%mvinsnstr ","
144 and
145 .BR \%mvwinsnstr "'s"
146 acceptance of negative
147 .I n
148 values is an
149 .I \%ncurses
150 extension.
151 .SH PORTABILITY
152 Applications employing
153 .I \%ncurses
154 extensions should condition their use on the visibility of the
155 .B \%NCURSES_VERSION
156 preprocessor macro.
157 .PP
158 X/Open Curses Issue\ 4 describes these functions.
159 It specifies no error conditions for them.
160 .PP
161 SVr4 describes a successful return value only as
162 \*(``an integer value other than
163 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 510
164 .PP
165 Issue\ 4 distinguished
166 .I \%insnstr
167 and
168 .I \%winsnstr
169 from the other functions documented above
170 by stating they \*(``do not perform wrapping\*(''.
171 This was probably an error,
172 since it makes this group of functions inconsistent.
173 No implementation of
174 .I curses
175 manifests this inconsistency,
176 and Issue\ 7 removed the claim.
177 .PP
178 Issue\ 4 states that the entire string is inserted if
179 .I n
180 is less than 1.
181 This is probably an error,
182 .\" ...copied from SVID 4, which made the same error; see p. 510.
183 because it is inconsistent with other functions
184 such as
185 .IR \%waddstr ","
186 and differs from the SVr4
187 .I curses
188 and Solaris
189 .I xcurses
190 implementations.
191 Nevertheless,
192 Issue\ 7 retains the language.
193 .SH HISTORY
194 SVr3.1 (1987)
195 introduced
196 .I \%winsstr
197 and
198 .I \%winsnstr
199 and their variants.
200 .SH SEE ALSO
201 \fB\%ins_wstr\fP(3NCURSES) describes comparable functions of the
202 .I \%ncurses
203 library in its wide-character configuration
204 .RI \%( ncursesw ).
205 .PP
206 \fB\%ncurses\fP(3NCURSES),
207 \fB\%inch\fP(3NCURSES),
208 \fB\%ins_wstr\fP(3NCURSES),
209 \fB\%util\fP(3NCURSES)