Debian Codegraph @

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

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.64 2025/08/16 19:56:13 tom Exp $
31 .TH addchstr 3NCURSES 2025-08-16 "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\%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(3NCURSES) describes the variants of these functions.
94 .PP
95 Because these functions do not call \fB\%waddch\fP(3NCURSES) internally,
96 they are faster than \fB\%waddstr\fP(3NCURSES) and \fB\%waddnstr\fP(3NCURSES).
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(3NCURSES);
105 .bP
106 do not update the cursor position to follow the last character written;
107 and
108 .bP
109 truncate the string at the window's right margin,
110 rather than wrapping it to the next line and potentially scrolling.
111 .SH RETURN VALUE
112 These functions return
113 .B OK
114 on success and
115 .B ERR
116 on failure.
117 .PP
118 In
119 .IR \%ncurses ","
120 these functions fail if
121 .bP
122 the
123 .I curses
124 screen has not been initialized,
125 .bP
126 .I chstr
127 is a null pointer,
128 or
129 .bP
130 (for functions taking a
131 .I \%WINDOW
132 pointer argument)
133 .I win
134 is a null pointer.
135 .PP
136 Functions prefixed with \*(``mv\*('' first perform cursor movement and
137 fail if the position
138 .RI ( y ,
139 .IR x )
140 is outside the window boundaries.
141 .SH NOTES
142 All of these functions except
143 .B \%waddchnstr
144 may be implemented as macros.
145 .SH PORTABILITY
146 X/Open Curses Issue\ 4 describes these functions.
147 It specifies no error conditions for them.
148 .PP
149 SVr4 describes a successful return value only as
150 \*(``an integer value other than
151 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 473
152 .SH HISTORY
153 SVr3.1 (1987)
154 introduced these functions.
155 .SH SEE ALSO
156 \fB\%add_wchstr\fP(3NCURSES) describes comparable functions of the
157 .I \%ncurses
158 library in its wide-character configuration
159 .RI \%( ncursesw ).
160 .PP
161 \fB\%ncurses\fP(3NCURSES),
162 \fB\%addch\fP(3NCURSES),
163 \fB\%addstr\fP(3NCURSES)