xref: /netbsd-src/lib/libcurses/curses_cchar.3 (revision 82d56013d7b633d116a93943de88e08335357a7c)
1.\"	$NetBSD: curses_cchar.3,v 1.2 2018/11/24 11:04:39 wiz Exp $
2.\"
3.\" Copyright (c) 2018 Valery Ushakov
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.Dd November 19, 2018
27.Dt CURSES_CCHAR 3
28.Os
29.Sh NAME
30.Nm curses_cchar ,
31.Nm getcchar ,
32.Nm setcchar
33.Nd curses representation of wide characters
34.Sh LIBRARY
35.Lb libcurses
36.Sh SYNOPSIS
37.\"
38.In curses.h
39.\"
40.Ft int
41.Fo getcchar
42.Fa "const cchar_t *wcval"
43.Fa "wchar_t *wch"
44.Fa "attr_t *attrs"
45.Fa "short *color_pair"
46.Fa "void *opts"
47.Fc
48.\"
49.Ft int
50.Fo setcchar
51.Fa "cchar_t *wcval"
52.Fa "const wchar_t *wch"
53.Fa "const attr_t attrs"
54.Fa "short color_pair"
55.Fa "const void *opts"
56.Fc
57.Sh DESCRIPTION
58Curses uses the opaque type
59.Vt cchar_t
60to represent a string of wide characters up to an
61implementation-dependent length along with a color pair and zero or
62more attributes.
63A null
64.Vt cchar_t
65object is an object that references an empty wide-character string.
66Arrays of
67.Vt cchar_t
68objects are terminated by a null
69.Vt cchar_t
70object.
71.Pp
72Objects of type
73.Vt cchar_t
74can be manipulated using the
75.Nm getcchar
76and
77.Nm setcchar
78functions.
79Both these functions take as their last parameter the
80.Fa opts
81argument which is reserved for future extensions.
82Currently, the application must provide a null pointer as
83.Fa opts .
84.\"
85.Pp
86When the
87.Nm getcchar
88function is called with non-null
89.Fa wch
90it extracts the information from the
91.Fa wcval
92object.
93The string of wide characters in
94.Fa wcval
95is copied to the
96.Fa wch
97array.
98The attributes are stored in
99.Fa attrs
100and the color pair is stored in
101.Fa color_pair .
102In this case it returns
103.Er OK
104upon successful completion, and
105.Er ERR
106otherwise.
107.Pp
108When
109.Nm getcchar
110is called with null
111.Fa wch
112it doesn't store any information but returns the number of wide
113characters referenced by
114.Fa wcval ,
115including the null terminator.
116.\"
117.Pp
118.Nm setcchar
119initializes
120.Fa wcval
121with the wide-character string
122.Fa wch ,
123attributes
124.Fa attrs ,
125and color pair
126.Fa color_pair .
127.Sh RETURN VALUES
128.Nm getchar
129called with null
130.Fa wch
131returns the the number of wide characters referenced by
132.Fa wcval ,
133including the null terminator.
134.Pp
135Otherwise these functions return one of the following values:
136.Bl -tag -width "Er ERR" -compact
137.It Er OK
138The function completed successfully.
139.It Er ERR
140An error occurred in the function.
141.El
142.\" .Sh SEE ALSO
143.\" XXX no other man pages yet for HAVE_WCHAR functions
144.Sh STANDARDS
145The
146.Nx
147Curses library complies with the X/Open Curses specification, part of
148the Single Unix Specification.
149.Sh HISTORY
150The Curses package appeared in
151.Bx 4.0 .
152.Pp
153Wide characters support appeared in
154.Nx 5.0 .
155