# curs_getcchar

## NAME



           **getcchar** , **setcchar** - Get a wide character string and rendition
           from a **cchar_t** or set a **cchar_t** from a wide-character 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_**,**
                   **const void ***_opts_ **);**
    


## DESCRIPTION



       **getcchar**
           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:
    
           •   Extracts information from a **cchar_t** value _wcval_
    
           •   Stores the character attributes in the location pointed to by
               _attrs_
    
           •   Stores the color-pair in the location pointed to by _color_pair_
    
           •   Stores the wide-character string, characters referenced by
               _wcval_ , into the array pointed to by _wch_.
    
           When _wch_ is a null pointer, the **getcchar** function does the
           following:
    
           •   Obtains the number of wide characters pointed to by _wcval_
    
           •   Does not change the data referenced by _attrs_ or _color_pair_
    
       **setcchar**
           The **setcchar** function initializes the location pointed to by _wcval_
           by using:
    
           •   The character attributes in _attrs_
    
           •   The color pair in _color_pair_
    
           •   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.
    


## EXTENSIONS



           X/Open Curses documents the _opts_ argument as reserved for future
           use, saying that it must be null.  This implementation uses that
           parameter in ABI 6 for the functions which have a color-pair
           parameter to support extended color pairs:
    
           •   For  functions  which modify the color, e.g., **setcchar** , if
               _opts_ is set it is treated as a pointer to **int** , and used to
               set  the  color pair instead of the **short** pair parameter.
    
           •   For functions which retrieve the color, e.g., **getcchar** , if
               _opts_ is set it is treated as a pointer to **int** , and  used  to
               retrieve  the color pair as an **int** value, in addition
               retrieving it via the standard pointer to **short** parameter.
    


## NOTES



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


## RETURN VALUE



           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**.  Otherwise, it
           returns **ERR**.
    


## PORTABILITY



           The **CCHARW_MAX** symbol is specific to ncurses.  X/Open Curses does
           not provide details for the layout of the **cchar_t** structure.  It
           tells what data are stored in it:
    
           •   a spacing character (**wchar_t** , i.e., 32-bits).
    
           •   non-spacing characters (again, **wchar_t** 's).
    
           •   attributes (at least 16 bits, inferred from the various ACS-
               and WACS-flags).
    
           •   color pair (at least 16 bits, inferred from the **unsigned short**
               type).
    
           The non-spacing characters are optional, in the sense that zero or
           more may be stored in a **cchar_t**.  XOpen/Curses specifies a limit:
    
               Implementations may limit the number of non-spacing characters
               that can be associated with a spacing character, provided any
               limit is at least 5.
    
           The Unix implementations at the time follow that limit:
    
           •   AIX 4 and OSF1 4 use the same declaration with an array of 5
               non-spacing characters _z_ and a single spacing character _c_.
    
           •   HP-UX 10 uses an opaque structure with 28 bytes, which is
               large enough for the 6 **wchar_t** values.
    
           •   Solaris _xpg4_ curses uses a single array of 6 **wchar_t** values.
    
           This implementation's **cchar_t** was defined in 1995 using **5** for the
           total of spacing and non-spacing characters (**CCHARW_MAX**).  That
           was probably due to a misreading of the AIX 4 header files,
           because the X/Open Curses document was not generally available at
           that time.  Later (in 2002), this detail was overlooked when
           beginning to implement the functions using the structure.
    
           In practice, even four non-spacing characters may seem enough.
           X/Open Curses documents possible uses for non-spacing characters,
           including using them for ligatures between characters (a feature
           apparently not supported by any curses implementation).  Unicode
           does not limit the (analogous) number of combining characters, so
           some applications may be affected.
    


* * *