Module Name: src
Committed By: uwe
Date: Mon Nov 19 01:08:22 UTC 2018
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/libcurses: Makefile
Added Files:
src/lib/libcurses: curses_cchar.3
Log Message:
Provide basic documentation on getcchar(3) and setcchar(3).
Looks like we don't have any of wide curses stuff documented, so this
seems to be a good place to start. Needs more exposition on wide
attr_t and how it's related to non-wide chtype, etc, etc.
To generate a diff of this commit:
cvs rdiff -u -r1.2238 -r1.2239 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.88 -r1.89 src/lib/libcurses/Makefile
cvs rdiff -u -r0 -r1.1 src/lib/libcurses/curses_cchar.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2238 src/distrib/sets/lists/comp/mi:1.2239
--- src/distrib/sets/lists/comp/mi:1.2238 Thu Nov 15 10:06:06 2018
+++ src/distrib/sets/lists/comp/mi Mon Nov 19 01:08:21 2018
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2238 2018/11/15 10:06:06 maxv Exp $
+# $NetBSD: mi,v 1.2239 2018/11/19 01:08:21 uwe Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -6247,6 +6247,7 @@
./usr/share/man/cat3/curses_attributes.0 comp-c-catman .cat
./usr/share/man/cat3/curses_background.0 comp-c-catman .cat
./usr/share/man/cat3/curses_border.0 comp-c-catman .cat
+./usr/share/man/cat3/curses_cchar.0 comp-c-catman .cat
./usr/share/man/cat3/curses_chgat.0 comp-c-catman .cat
./usr/share/man/cat3/curses_clear.0 comp-c-catman .cat
./usr/share/man/cat3/curses_color.0 comp-c-catman .cat
@@ -7111,6 +7112,7 @@
./usr/share/man/cat3/getc.0 comp-c-catman .cat
./usr/share/man/cat3/getc_unlocked.0 comp-c-catman .cat
./usr/share/man/cat3/getcap.0 comp-obsolete obsolete
+./usr/share/man/cat3/getcchar.0 comp-obsolete obsolete
./usr/share/man/cat3/getch.0 comp-c-catman .cat
./usr/share/man/cat3/getchar.0 comp-c-catman .cat
./usr/share/man/cat3/getchar_unlocked.0 comp-c-catman .cat
@@ -9461,6 +9463,7 @@
./usr/share/man/cat3/set_top_row.0 comp-c-catman .cat
./usr/share/man/cat3/setbuf.0 comp-c-catman .cat
./usr/share/man/cat3/setbuffer.0 comp-c-catman .cat
+./usr/share/man/cat3/setcchar.0 comp-c-catman .cat
./usr/share/man/cat3/setclasscontext.0 comp-c-catman .cat
./usr/share/man/cat3/setdisktab.0 comp-c-catman .cat
./usr/share/man/cat3/setdomainname.0 comp-c-catman .cat
@@ -14151,6 +14154,7 @@
./usr/share/man/html3/curses_attributes.html comp-c-htmlman html
./usr/share/man/html3/curses_background.html comp-c-htmlman html
./usr/share/man/html3/curses_border.html comp-c-htmlman html
+./usr/share/man/html3/curses_cchar.html comp-c-htmlman html
./usr/share/man/html3/curses_chgat.html comp-c-htmlman html
./usr/share/man/html3/curses_clear.html comp-c-htmlman html
./usr/share/man/html3/curses_color.html comp-c-htmlman html
@@ -15023,6 +15027,7 @@
./usr/share/man/html3/getc.html comp-c-htmlman html
./usr/share/man/html3/getc_unlocked.html comp-c-htmlman html
./usr/share/man/html3/getcap.html comp-obsolete obsolete
+./usr/share/man/html3/getcchar.html comp-c-htmlman html
./usr/share/man/html3/getch.html comp-c-htmlman html
./usr/share/man/html3/getchar.html comp-c-htmlman html
./usr/share/man/html3/getchar_unlocked.html comp-c-htmlman html
@@ -17352,6 +17357,7 @@
./usr/share/man/html3/set_top_row.html comp-c-htmlman html
./usr/share/man/html3/setbuf.html comp-c-htmlman html
./usr/share/man/html3/setbuffer.html comp-c-htmlman html
+./usr/share/man/html3/setcchar.html comp-c-htmlman html
./usr/share/man/html3/setclasscontext.html comp-c-htmlman html
./usr/share/man/html3/setdisktab.html comp-c-htmlman html
./usr/share/man/html3/setdomainname.html comp-c-htmlman html
@@ -21997,6 +22003,7 @@
./usr/share/man/man3/curses_attributes.3 comp-c-man .man
./usr/share/man/man3/curses_background.3 comp-c-man .man
./usr/share/man/man3/curses_border.3 comp-c-man .man
+./usr/share/man/man3/curses_cchar.3 comp-c-man .man
./usr/share/man/man3/curses_chgat.3 comp-c-man .man
./usr/share/man/man3/curses_clear.3 comp-c-man .man
./usr/share/man/man3/curses_color.3 comp-c-man .man
@@ -22872,6 +22879,7 @@
./usr/share/man/man3/getc.3 comp-c-man .man
./usr/share/man/man3/getc_unlocked.3 comp-c-man .man
./usr/share/man/man3/getcap.3 comp-obsolete obsolete
+./usr/share/man/man3/getcchar.3 comp-c-man .man
./usr/share/man/man3/getch.3 comp-c-man .man
./usr/share/man/man3/getchar.3 comp-c-man .man
./usr/share/man/man3/getchar_unlocked.3 comp-c-man .man
@@ -25246,6 +25254,7 @@
./usr/share/man/man3/set_top_row.3 comp-c-man .man
./usr/share/man/man3/setbuf.3 comp-c-man .man
./usr/share/man/man3/setbuffer.3 comp-c-man .man
+./usr/share/man/man3/setcchar.3 comp-c-man .man
./usr/share/man/man3/setclasscontext.3 comp-c-man .man
./usr/share/man/man3/setdisktab.3 comp-c-man .man
./usr/share/man/man3/setdomainname.3 comp-c-man .man
Index: src/lib/libcurses/Makefile
diff -u src/lib/libcurses/Makefile:1.88 src/lib/libcurses/Makefile:1.89
--- src/lib/libcurses/Makefile:1.88 Sun Nov 18 01:23:57 2018
+++ src/lib/libcurses/Makefile Mon Nov 19 01:08:22 2018
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.88 2018/11/18 01:23:57 uwe Exp $
+# $NetBSD: Makefile,v 1.89 2018/11/19 01:08:22 uwe Exp $
# @(#)Makefile 8.2 (Berkeley) 1/2/94
.include <bsd.own.mk>
@@ -28,6 +28,7 @@ SRCS= acs.c addbytes.c addch.c addchnstr
MAN= curses.3 curses_addch.3 curses_addchstr.3 curses_addstr.3 \
curses_attributes.3 curses_background.3 curses_border.3 \
+ curses_cchar.3 \
curses_chgat.3 curses_clear.3 curses_color.3 \
curses_cursor.3 curses_default_colors.3 \
curses_delch.3 curses_deleteln.3 curses_echochar.3 curses_fileio.3 \
@@ -60,6 +61,8 @@ MLINKS+= curses_addch.3 addch.3 curses_a
curses_attributes.3 attrset.3 curses_tty.3 beep.3 \
curses_background.3 bkgd.3 curses_background.3 bkgdset.3 \
curses_border.3 border.3 curses_border.3 box.3 \
+ curses_cchar.3 getcchar.3 \
+ curses_cchar.3 setcchar.3 \
curses_chgat.3 chgat.3 curses_chgat.3 mvchgat.3 \
curses_chgat.3 mvwchgat.3 curses_chgat.3 wchgat.3 \
curses_color.3 can_change_color.3 curses_tty.3 cbreak.3 \
Added files:
Index: src/lib/libcurses/curses_cchar.3
diff -u /dev/null src/lib/libcurses/curses_cchar.3:1.1
--- /dev/null Mon Nov 19 01:08:22 2018
+++ src/lib/libcurses/curses_cchar.3 Mon Nov 19 01:08:22 2018
@@ -0,0 +1,154 @@
+.\" $NetBSD: curses_cchar.3,v 1.1 2018/11/19 01:08:22 uwe Exp $
+.\"
+.\" Copyright (c) 2018 Valery Ushakov
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 19, 2018
+.Dt CURSES_CCHAR 3
+.Os
+.Sh NAME
+.Nm curses_cchar ,
+.Nm getcchar ,
+.Nm setcchar
+.Nd curses representation of wide characters
+.Sh LIBRARY
+.Lb libcurses
+.Sh SYNOPSIS
+.\"
+.In curses.h
+.\"
+.Ft int
+.Fo getcchar
+.Fa "const cchar_t *wcval"
+.Fa "wchar_t *wch"
+.Fa "attr_t *attrs"
+.Fa "short *color_pair"
+.Fa "void *opts"
+.Fc
+.\"
+.Ft int
+.Fo setcchar
+.Fa "cchar_t *wcval"
+.Fa "const wchar_t *wch"
+.Fa "const attr_t attrs"
+.Fa "short color_pair"
+.Fa "const void *opts"
+.Fc
+.Sh DESCRIPTION
+Curses uses opaque type
+.Vt cchar_t
+to represent a string of wide characters up to an
+implementation-dependent length along with a color pair and zero or
+more attributes.
+A null
+.Vt cchar_t
+object is an object that references an empty wide-character string.
+Arrays of
+.Vt cchar_t
+objects are terminated by a null
+.Vt cchar_t
+object.
+.Pp
+Objects of type
+.Vt cchar_t
+can be manipulated using
+.Nm getcchar
+and
+.Nm setcchar
+functions.
+Both these functions take as their last paramter the
+.Fa opts
+argument which is reserved for future extensions.
+Currently, the application must provide a null pointer as
+.Fa opts .
+.\"
+.Pp
+When
+.Nm getcchar
+function is called with non-null
+.Fa wch
+it extracts the information from the
+.Fa wcval
+object.
+The string of wide characters in
+.Fa wcval
+is copied to the
+.Fa wch
+array.
+The attributes are stored in
+.Fa attrs ,
+and the color pair is stored in
+.Fa color_pair .
+In this case it returns
+.Er OK
+upon successful completion, and
+.Er ERR
+otherwise.
+.Pp
+When
+.Nm getcchar
+is called with null
+.Fa wch
+it doesn't store any information but returns the number of wide
+characters referenced by
+.Fa wcval ,
+including the null terminator.
+.\"
+.Pp
+.Nm setcchar
+initializes
+.Fa wcval
+with the wide-character string
+.Fa wch ,
+attributes
+.Fa attrs ,
+and color pair
+.Fa color_pair .
+.Sh RETURN VALUES
+.Nm getchar
+called with null
+.Fa wch
+returns the the number of wide characters referenced by
+.Fa wcval ,
+including the null terminator.
+.Pp
+Otherwise these functions return one of the following values:
+.Bl -tag -width "Er ERR" -compact
+.It Er OK
+The function completed successfully.
+.It Er ERR
+An error occurred in the function.
+.El
+.\" .Sh SEE ALSO
+.\" XXX no other man pages yet for HAVE_WCHAR functions
+.Sh STANDARDS
+The
+.Nx
+Curses library complies with the X/Open Curses specification, part of
+the Single Unix Specification.
+.Sh HISTORY
+The Curses package appeared in
+.Bx 4.0 .
+.Pp
+Wide characters support appeared in
+.Nx 5.0 .
