Debian Codegraph @

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