Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
3 .\" Copyright 2001-2015,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_getcchar.3x,v 1.57 2025/02/23 13:48:31 tom Exp $
31 .TH getcchar 3NCURSES 2025-02-23 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds ' \(aq
34 .\}
35 .el \{\
36 .ie t .ds ' \(aq
37 .el .ds ' '
38 .\}
39 .
40 .de bP
41 .ie n .IP \(bu 4
42 .el .IP \(bu 2
43 ..
44 .SH NAME
45 \fB\%getcchar\fP,
46 \fB\%setcchar\fP \-
47 convert between a wide-character string and a \fIcurses\fR complex character
48 .SH SYNOPSIS
49 .nf
50 \fB#include <curses.h>
51 .PP
52 \fBint getcchar(const cchar_t * \fIwch\fP, wchar_t * \fIwc\fP,
53 attr_t * \fIattrs\fP, short * \fIpair\fP, void * \fIopts\fP);
54 \fBint setcchar(cchar_t * \fIwch\fP, const wchar_t * \fIwc\fP,
55 const attr_t \fIattrs\fP, short \fIpair\fP, const void * \fIopts\fP);
56 .fi
57 .SH DESCRIPTION
58 The
59 .I curses
60 complex character data type
61 .I \%cchar_t
62 is a structure type comprising
63 a wide-character string,
64 a set of attributes,
65 and
66 a color pair identifier.
67 The
68 .I \%cchar_t
69 structure is opaque;
70 do not attempt to access its members directly.
71 The library provides functions to manipulate this type.
72 .SS getcchar
73 .B \%getcchar
74 destructures a
75 .I \%cchar_t
76 into its components.
77 .PP
78 If
79 .I wc
80 is not a null pointer,
81 .BR \%getcchar :
82 .bP
83 stores the wide-character string in the
84 .I curses
85 complex character
86 .I wch
87 into
88 .IR wc ;
89 .bP
90 stores the attributes in
91 .IR attrs ;
92 and
93 .bP
94 stores the color pair identifier in
95 .IR pair .
96 .PP
97 If
98 .I wc
99 is a null pointer,
100 .B \%getcchar
101 counts the
102 .I \%wchar_t
103 wide characters in
104 .IR wch ,
105 returns that value,
106 and leaves
107 .I attrs
108 and
109 .I pair
110 unchanged.
111 .SS setcchar
112 .B \%setcchar
113 constructs a
114 .I curses
115 complex character
116 .I wch
117 from the components
118 .IR wc ,
119 .IR attrs ,
120 and
121 .IR pair .
122 The wide-character string
123 .I wch
124 must be terminated with a null wide character
125 .B L\*'\e0\*'
126 and must contain at most one spacing character,
127 which,
128 if present,
129 must be the first wide character in the string.
130 .PP
131 Up to
132 .BR \%CCHARW_MAX\ \-\ 1
133 non-spacing characters may follow
134 (see \fB\%curses_variables\fP(3NCURSES)).
135 .I \%ncurses
136 ignores any additional non-spacing characters.
137 .PP
138 The string may contain a single control character instead.
139 In that case,
140 no non-spacing characters are allowed.
141 .SH RETURN VALUE
142 If
143 .B \%getcchar
144 is passed a null pointer as its
145 .I wc
146 argument,
147 it returns the number of wide characters for a given
148 .I wch
149 that it would store in
150 .IR wc ","
151 counting a trailing null wide character.
152 If
153 .B \%getcchar
154 is not passed a null pointer as its
155 .I wc
156 argument,
157 it returns
158 .B OK
159 on success and
160 .B ERR
161 on failure.
162 .PP
163 In
164 .IR \%ncurses ,
165 .B \%getcchar
166 returns
167 .B ERR
168 if either
169 .I attrs
170 or
171 .I pair
172 is a null pointer and
173 .I wc
174 is not.
175 .PP
176 .B \%setcchar
177 returns
178 .B OK
179 on success and
180 .B ERR
181 on failure.
182 .PP
183 In
184 .IR \%ncurses ,
185 .B \%setcchar
186 returns
187 .B ERR
188 if
189 .bP
190 .I wch
191 is a null pointer,
192 .bP
193 .I wc
194 starts with a (wide) control character
195 and contains any other wide characters,
196 or
197 .bP
198 .I pair
199 has a negative value.
200 .SH NOTES
201 .I wch
202 may be a value stored by
203 .B \%setcchar
204 or another
205 .I curses
206 function with a writable
207 .I \%cchar_t
208 argument.
209 If
210 .I wch
211 is constructed by any other means,
212 the library's behavior is unspecified.
213 .SH EXTENSIONS
214 X/Open Curses documents the
215 .I opts
216 argument as reserved for future use,
217 saying that it must be a null pointer.
218 The
219 .IR \%ncurses \ 6
220 ABI uses it with functions that have a color pair parameter
221 to support extended color pairs.
222 .bP
223 In functions that assign colors,
224 such as
225 .BR \%setcchar ","
226 if
227 .I opts
228 is not a null pointer,
229 .I \%ncurses
230 treats it as a pointer to
231 .IR int ","
232 and interprets it instead of the
233 .I short
234 .I pair
235 parameter as a color pair identifier.
236 .bP
237 In functions that retrieve colors,
238 such as
239 .BR \%getcchar ","
240 if
241 .I opts
242 is not a null pointer,
243 .I \%ncurses
244 treats it as a pointer to
245 .IR int ","
246 and stores the retrieved color pair identifier there
247 as well as in the
248 .I short
249 .I pair
250 parameter
251 (which may therefore undergo a narrowing conversion).
252 .SH PORTABILITY
253 Applications employing
254 .I \%ncurses
255 extensions should condition their use on the visibility of the
256 .B \%NCURSES_VERSION
257 preprocessor macro.
258 .PP
259 These functions are described in X/Open Curses Issue\ 4.
260 It specifies no error conditions for them.
261 .PP
262 X/Open Curses does not detail the layout of the
263 .I \%cchar_t
264 structure,
265 describing only its minimal required contents:
266 .bP
267 a spacing wide character
268 .RI \%( wchar_t ),
269 .bP
270 at least five non-spacing wide characters
271 .RI \%( wchar_t ;
272 see below),
273 .bP
274 attributes
275 (at least 15 bits' worth,
276 inferred from the count of specified
277 .I WA_
278 constants),
279 .\" See X/Open Curses Issue 7, p. 307.
280 .bP
281 a color pair identifier
282 (at least 16 bits,
283 inferred from the
284 .I short
285 type used to encode it).
286 .PP
287 Non-spacing characters are optional,
288 in the sense that zero or more may be stored in a
289 .IR \%cchar_t "."
290 XOpen/Curses specifies a limit:
291 .RS 4
292 .PP
293 Implementations may limit the number of non-spacing characters that can
294 be associated with a spacing character,
295 provided any limit is at least 5.
296 .RE
297 .PP
298 Then-contemporary Unix implementations adhered to that limit.
299 .bP
300 AIX\ 4 and OSF/1\ 4 used the same declaration with
301 a single spacing wide character
302 .I c
303 and an array of 5 non-spacing wide characters
304 .IR z "."
305 .bP
306 HP-UX\ 10 used an opaque structure of 28 bytes,
307 large enough for 6
308 .I \%wchar_t
309 values.
310 .bP
311 Solaris
312 .I xcurses
313 uses a single array of 6
314 .I \%wchar_t
315 values.
316 .PP
317 .I \%ncurses
318 defined its
319 .I \%cchar_t
320 in 1995 using 5 as the
321 .I total
322 of spacing and non-spacing characters
323 .RB \%( CCHARW_MAX ).
324 That was probably due to a misreading of the AIX\ 4 header files,
325 because the X/Open Curses document
326 was not generally available at that time.
327 Later (in 2002),
328 this detail was overlooked when work began to implement the functions
329 using the structure.
330 .PP
331 In practice,
332 a mere four non-spacing characters may seem adequate.
333 X/Open Curses documents possible applications of non-spacing characters,
334 including their use as ligatures
335 (a feature apparently not supported by any
336 .I curses
337 implementation).
338 Unicode does not limit the (analogous) number of combining characters
339 in a grapheme cluster;
340 some applications may be affected.
341 .I \%ncurses
342 can be compiled with a different
343 .B CCHARW_MAX
344 value;
345 doing so alters the library's ABI.
346 .SH HISTORY
347 X/Open Curses Issue\ 4 (1995) initially specified these functions.
348 .SH SEE ALSO
349 \fB\%ncurses\fP(3NCURSES),
350 \fB\%attr\fP(3NCURSES),
351 \fB\%color\fP(3NCURSES),
352 \fB\%wcwidth\fP(3)