# curs_getcchar 3x

    curs_getcchar(3x)                                     curs_getcchar(3x)

## NAME

           getcchar,  setcchar - Get a wide character string and ren-
           dition from a cchar_t or set a cchar_t from a wide-charac-
           ter string

## SYNOPSIS

           #include <curses.h>

           int getcchar(
                   const cchar_t *wcval,
                   wchar_t *wch,
                   attr_t *attrs,
                   short *color_pair,
                   void *opts );

           int setcchar(
                   cchar_t *wcval,
                   const wchar_t *wch,
                   const attr_t attrs,
                   short color_pair,
                   void *opts );

## DESCRIPTION

           The  getcchar  function  gets  a wide-character string and
           rendition from a cchar_t argument.  When wch is not a null
           pointer, the getcchar function does the following:

           o   Extracts information from a cchar_t value wcval

           o   Stores   the  character  attributes  in  the  location
               pointed to by attrs

           o   Stores the color-pair in the location  pointed  to  by
               color_pair

           o   Stores  the  wide-character  string, characters refer-
               enced by wcval, into the array pointed to by wch.

           When wch is a null pointer, the getcchar function does the
           following:

           o   Obtains  the  number  of wide characters pointed to by
               wcval

           o   Does not  change  the  data  referenced  by  attrs  or
               color_pair

           The  setcchar function initializes the location pointed to
           by wcval by using:

           o   The character attributes in attrs

           o   The color pair in color_pair

           o   The wide-character string  pointed  to  by  wch.   The
               string  must  be L'\0' terminated, contain at most one
               spacing character, which must be the first.

               Up to CCHARW_MAX-1 nonspacing characters  may  follow.
               Additional nonspacing characters are ignored.

               The  string  may  contain  a  single control character
               instead.  In that case, no nonspacing  characters  are
               allowed.

## NOTES

           The  opts argument is reserved for future use.  Currently,
           an application must provide a null pointer as opts.

           The wcval argument may be a value generated by a  call  to
           setcchar  or by a function that has a cchar_t output argu-
           ment.  If wcval is constructed by  any  other  means,  the
           effect is unspecified.

## RETURN VALUES

           When wch is a null pointer, getcchar returns the number of
           wide characters referenced by wcval, including one  for  a
           trailing null.

           When  wch  is not a null pointer, getcchar returns OK upon
           successful completion, and ERR otherwise.

           Upon successful completion, setcchar returns  OK.   Other-
           wise, it returns ERR.

## SEE ALSO

           Functions:   curs_attr(3x),   curs_color(3x),  curses(3x),
           wcwidth(3).

                                                          curs_getcchar(3x)