Debian Codegraph @

upstream/mageia-cauldron/man3/curs_addchstr.3x

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2012,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_addchstr.3x,v 1.62 2025/03/15 20:41:04 tom Exp $
31 .TH curs_addchstr 3X 2025-03-15 "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\%addchstr\fP,
49 \fB\%waddchstr\fP,
50 \fB\%mvaddchstr\fP,
51 \fB\%mvwaddchstr\fP,
52 \fB\%addchnstr\fP,
53 \fB\%waddchnstr\fP,
54 \fB\%mvaddchnstr\fP,
55 \fB\%mvwaddchnstr\fP \-
56 add a \fIcurses\fR character string to a window
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint addchstr(const chtype * \fIchstr\fP);
62 \fBint waddchstr(WINDOW * \fIwin\fP, const chtype * \fIchstr\fP);
63 \fBint mvaddchstr(int \fIy\fP, int \fIx\fP, const chtype * \fIchstr\fP);
64 \fBint mvwaddchstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP,
65 const chtype * \fIchstr\fP);
66 .PP
67 \fBint addchnstr(const chtype * \fIchstr\fP, int \fIn\fP);
68 \fBint waddchnstr(WINDOW * \fIwin\fP, const chtype * \fIchstr\fP, int \fIn\fP);
69 \fBint mvaddchnstr(int \fIy\fP, int \fIx\fP, const chtype * \fIchstr\fP, int \fIn\fP);
70 \fBint mvwaddchnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP,
71 const chtype * \fIchstr\fP, int \fIn\fP);
72 .fi
73 .SH DESCRIPTION
74 .B \%waddchstr
75 copies the string of
76 .I curses
77 characters
78 .I \%chstr
79 to the window
80 .IR win "."
81 A null
82 .I curses
83 character terminates the string.
84 .B \%waddchnstr
85 does the same,
86 but copies at most
87 .I n
88 characters,
89 or as many as possible if
90 .I n
91 is
92 .BR \-1 "."
93 \fB\%ncurses\fP(3X) describes the variants of these functions.
94 .PP
95 Because these functions do not call \fB\%waddch\fP(3X) internally,
96 they are faster than \fB\%waddstr\fP(3X) and \fB\%waddnstr\fP(3X).
97 On the other hand,
98 they
99 .bP
100 do not treat the backspace,
101 carriage return,
102 or line feed characters specially;
103 .bP
104 do not represent unprintable characters with \fB\%unctrl\fP(3X);
105 .bP
106 do not update the cursor position to follow the last character written;
107 .bP
108 truncate the string at the window's right margin,
109 rather than wrapping it to the next line and potentially scrolling.
110 .SH RETURN VALUE
111 These functions return
112 .B OK
113 on success and
114 .B ERR
115 on failure.
116 .PP
117 In
118 .IR \%ncurses ","
119 these functions fail if
120 .bP
121 the
122 .I curses
123 screen has not been initialized,
124 .bP
125 .I chstr
126 is a null pointer,
127 or
128 .bP
129 (for functions taking a
130 .I \%WINDOW
131 pointer argument)
132 .I win
133 is a null pointer.
134 .PP
135 Functions prefixed with \*(``mv\*('' first perform cursor movement and
136 fail if the position
137 .RI ( y ,
138 .IR x )
139 is outside the window boundaries.
140 .SH NOTES
141 All of these functions except
142 .B \%waddchnstr
143 may be implemented as macros.
144 .SH PORTABILITY
145 X/Open Curses Issue\ 4 describes these functions.
146 It specifies no error conditions for them.
147 .PP
148 SVr4 describes a successful return value only as
149 \*(``an integer value other than
150 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 473
151 .SH HISTORY
152 SVr3.1 (1987)
153 introduced these functions.
154 .SH SEE ALSO
155 \fB\%curs_add_wchstr\fP(3X) describes comparable functions of the
156 .I \%ncurses
157 library in its wide-character configuration
158 .RI \%( ncursesw ).
159 .PP
160 \fB\%curses\fP(3X),
161 \fB\%curs_addch\fP(3X),
162 \fB\%curs_addstr\fP(3X)