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