Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 2002-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_in_wchstr.3x,v 1.56 2025/10/21 00:03:06 tom Exp $
31 .TH in_wchstr 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\%in_wchstr\fP,
49 \fB\%in_wchnstr\fP,
50 \fB\%win_wchstr\fP,
51 \fB\%win_wchnstr\fP,
52 \fB\%mvin_wchstr\fP,
53 \fB\%mvin_wchnstr\fP,
54 \fB\%mvwin_wchstr\fP,
55 \fB\%mvwin_wchnstr\fP \-
56 get a \fIcurses\fR complex character string from a window
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint in_wchstr(cchar_t * \fIwchstr\fP);
62 \fBint win_wchstr(WINDOW * \fIwin\fP, cchar_t * \fIwchstr\fP);
63 \fBint mvin_wchstr(int \fIy\fP, int \fIx\fP, cchar_t * \fIwchstr\fP);
64 \fBint mvwin_wchstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t * \fIwchstr\fP);
65 .PP
66 \fBint in_wchnstr(cchar_t * \fIwchstr\fP, int \fIn\fP);
67 \fBint win_wchnstr(WINDOW * \fIwin\fP, cchar_t * \fIwchstr\fP, int \fIn\fP);
68 \fBint mvin_wchnstr(int \fIy\fP, int \fIx\fP, cchar_t * \fIwchstr\fP, int \fIn\fP);
69 \fBint mvwin_wchnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t * \fIwchstr\fP, int \fIn\fP)
70 .fi
71 .SH DESCRIPTION
72 .B \%win_wchstr
73 extracts a
74 .I curses
75 complex 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 wchstr ","
82 terminating it with a wide null
83 .I curses
84 character.
85 .B \%win_wchnstr
86 does the same,
87 but copies at most
88 .I n
89 .I curses
90 complex characters from
91 .IR win "."
92 A negative
93 .I n
94 implies no limit;
95 .B \%win_wchnstr
96 then works like
97 .BR \%win_wchstr "."
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 wchstr
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 \%win_wchnstr
132 may be implemented as macros.
133 .PP
134 Reading a line that overflows the array pointed to by
135 .I wchstr
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 wchstr "."
144 .SH PORTABILITY
145 X/Open Curses Issue\ 4 describes these functions.
146 It specifies no error conditions for them.
147 .SH HISTORY
148 X/Open Curses Issue\ 4 (1995) initially specified these functions.
149 The System\ V Interface Definition Version\ 4
150 of the same year
151 specified a function named
152 .I \%winwchstr
153 (and the usual variants).
154 .\" SVID 4, vol 3., p. 515
155 This was a later addition to
156 .RI SVr4. x ,
157 not appearing in the first SVr4 (1989).
158 It differed from X/Open's later
159 .I \%win_wchstr
160 in that it took an argument of type
161 .RI pointer-to- chtype
162 instead of
163 .RI pointer-to- cchar_t "."
164 .SH SEE ALSO
165 \fB\%inchstr\fP(3NCURSES) describes comparable functions of the
166 .I \%ncurses
167 library in its non-wide-character configuration.
168 .PP
169 \fB\%ncurses\fP(3NCURSES),
170 \fB\%inwstr\fP(3NCURSES),
171 \fB\%in_wch\fP(3NCURSES)