1 <!DOCTYPE HTML PUBLIC
"-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 2001-2009,2010 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_getcchar.3x,v 1.15 2010/12/04 18:36:44 tom Exp @
34 <TITLE>curs_getcchar
3x
</TITLE>
35 <link rev=made
href=
"mailto:bug-ncurses@gnu.org">
36 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1">
39 <H1>curs_getcchar
3x
</H1>
42 <!-- Manpage converted by man2html 3.0.1 -->
43 <STRONG><A HREF=
"curs_getcchar.3x.html">curs_getcchar(
3x)
</A></STRONG> <STRONG><A HREF=
"curs_getcchar.3x.html">curs_getcchar(
3x)
</A></STRONG>
50 <STRONG>getcchar
</STRONG>,
<STRONG>setcchar
</STRONG> - Get a wide character string and ren-
51 dition from a
<STRONG>cchar_t
</STRONG> or set a
<STRONG>cchar_t
</STRONG> from a wide-charac-
56 <H2>SYNOPSIS
</H2><PRE>
57 <STRONG>#include
</STRONG> <STRONG><curses.h
></STRONG>
59 <STRONG>int
</STRONG> <STRONG>getcchar(
</STRONG>
60 <STRONG>const
</STRONG> <STRONG>cchar_t
</STRONG> <STRONG>*
</STRONG><EM>wcval
</EM><STRONG>,
</STRONG>
61 <STRONG>wchar_t
</STRONG> <STRONG>*
</STRONG><EM>wch
</EM><STRONG>,
</STRONG>
62 <STRONG>attr_t
</STRONG> <STRONG>*
</STRONG><EM>attrs
</EM><STRONG>,
</STRONG>
63 <STRONG>short
</STRONG> <STRONG>*
</STRONG><EM>color
</EM><STRONG>_
</STRONG><EM>pair
</EM><STRONG>,
</STRONG>
64 <STRONG>void
</STRONG> <STRONG>*
</STRONG><EM>opts
</EM> <STRONG>);
</STRONG>
66 <STRONG>int
</STRONG> <STRONG>setcchar(
</STRONG>
67 <STRONG>cchar_t
</STRONG> <STRONG>*
</STRONG><EM>wcval
</EM><STRONG>,
</STRONG>
68 <STRONG>const
</STRONG> <STRONG>wchar_t
</STRONG> <STRONG>*
</STRONG><EM>wch
</EM><STRONG>,
</STRONG>
69 <STRONG>const
</STRONG> <STRONG>attr_t
</STRONG> <EM>attrs
</EM><STRONG>,
</STRONG>
70 <STRONG>short
</STRONG> <EM>color
</EM><STRONG>_
</STRONG><EM>pair
</EM><STRONG>,
</STRONG>
71 <STRONG>void
</STRONG> <STRONG>*
</STRONG><EM>opts
</EM> <STRONG>);
</STRONG>
75 <H2>DESCRIPTION
</H2><PRE>
76 The
<STRONG>getcchar
</STRONG> function gets a wide-character string and
77 rendition from a
<STRONG>cchar_t
</STRONG> argument. When
<EM>wch
</EM> is not a null
78 pointer, the
<STRONG>getcchar
</STRONG> function does the following:
80 <STRONG>o
</STRONG> Extracts information from a
<STRONG>cchar_t
</STRONG> value
<EM>wcval
</EM>
82 <STRONG>o
</STRONG> Stores the character attributes in the location
83 pointed to by
<EM>attrs
</EM>
85 <STRONG>o
</STRONG> Stores the color-pair in the location pointed to by
86 <EM>color
</EM><STRONG>_
</STRONG><EM>pair
</EM>
88 <STRONG>o
</STRONG> Stores the wide-character string, characters refer-
89 enced by
<EM>wcval
</EM>, into the array pointed to by
<EM>wch
</EM>.
91 When
<EM>wch
</EM> is a null pointer, the
<STRONG>getcchar
</STRONG> function does the
94 <STRONG>o
</STRONG> Obtains the number of wide characters pointed to by
97 <STRONG>o
</STRONG> Does not change the data referenced by
<EM>attrs
</EM> or
98 <EM>color
</EM><STRONG>_
</STRONG><EM>pair
</EM>
100 The
<STRONG>setcchar
</STRONG> function initializes the location pointed to
101 by
<EM>wcval
</EM> by using:
103 <STRONG>o
</STRONG> The character attributes in
<EM>attrs
</EM>
105 <STRONG>o
</STRONG> The color pair in
<EM>color
</EM><STRONG>_
</STRONG><EM>pair
</EM>
107 <STRONG>o
</STRONG> The wide-character string pointed to by
<EM>wch
</EM>. The
108 string must be L'\
0' terminated, contain at most one
109 spacing character, which must be the first.
111 Up to
<STRONG>CCHARW_MAX
</STRONG>-
1 nonspacing characters may follow.
112 Additional nonspacing characters are ignored.
114 The string may contain a single control character
115 instead. In that case, no nonspacing characters are
121 The
<EM>opts
</EM> argument is reserved for future use. Currently,
122 an application must provide a null pointer as
<EM>opts
</EM>.
124 The
<EM>wcval
</EM> argument may be a value generated by a call to
125 <STRONG>setcchar
</STRONG> or by a function that has a
<STRONG>cchar_t
</STRONG> output argu-
126 ment. If
<EM>wcval
</EM> is constructed by any other means, the
127 effect is unspecified.
131 <H2>RETURN VALUES
</H2><PRE>
132 When
<EM>wch
</EM> is a null pointer,
<STRONG>getcchar
</STRONG> returns the number of
133 wide characters referenced by
<EM>wcval
</EM>, including one for a
136 When
<EM>wch
</EM> is not a null pointer,
<STRONG>getcchar
</STRONG> returns
<STRONG>OK
</STRONG> upon
137 successful completion, and
<STRONG>ERR
</STRONG> otherwise.
139 Upon successful completion,
<STRONG>setcchar
</STRONG> returns
<STRONG>OK
</STRONG>. Other-
140 wise, it returns
<STRONG>ERR
</STRONG>.
144 <H2>SEE ALSO
</H2><PRE>
145 Functions:
<STRONG><A HREF=
"curs_attr.3x.html">curs_attr(
3x)
</A></STRONG>,
<STRONG><A HREF=
"curs_color.3x.html">curs_color(
3x)
</A></STRONG>,
<STRONG><A HREF=
"ncurses.3x.html">curses(
3x)
</A></STRONG>,
146 <STRONG><A HREF=
"wcwidth.3.html">wcwidth(
3)
</A></STRONG>.
150 <STRONG><A HREF=
"curs_getcchar.3x.html">curs_getcchar(
3x)
</A></STRONG>
154 Man(
1) output converted with
155 <a href=
"http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html
</a>