ncurses 5.9 - patch 20131221
[ncurses.git] / doc / html / man / curs_getcchar.3x.html
index 235e41c9fb413d59a44fb9311246ec6a48d6f825..6bd64861116bca561f9f197c18a3a1a516cdcb05 100644 (file)
@@ -1,7 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <!-- 
   ****************************************************************************
-  * Copyright (c) 2001-2003,2006 Free Software Foundation, Inc.              *
+  * Copyright (c) 2001-2010,2012 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
@@ -27,7 +27,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_getcchar.3x,v 1.10 2006/12/24 16:00:02 tom Exp @
+  * @Id: curs_getcchar.3x,v 1.16 2012/11/03 23:03:59 tom Exp @
 -->
 <HTML>
 <HEAD>
        rendition from a <STRONG>cchar_t</STRONG> argument.  When <EM>wch</EM> is not a null
        pointer, the <STRONG>getcchar</STRONG> function does the following:
 
-          Extracts information from a <STRONG>cchar_t</STRONG> value <EM>wcval</EM>
+       <STRONG>o</STRONG>   Extracts information from a <STRONG>cchar_t</STRONG> value <EM>wcval</EM>
 
-       -    Stores  the  character  attributes  in  the  location
-            pointed to by <EM>attrs</EM>
+       <STRONG>o</STRONG>   Stores   the  character  attributes  in  the  location
+           pointed to by <EM>attrs</EM>
 
-       -    Stores the color-pair in the location pointed  to  by
-            <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
+       <STRONG>o</STRONG>   Stores the color-pair in the location  pointed  to  by
+           <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
 
-       -    Stores  the  wide-character string, characters refer-
-            enced by <EM>wcval</EM>, into the array pointed to by <EM>wch</EM>.
+       <STRONG>o</STRONG>   Stores  the  wide-character  string, characters refer-
+           enced by <EM>wcval</EM>, into the array pointed to by <EM>wch</EM>.
 
        When <EM>wch</EM> is a null pointer, the <STRONG>getcchar</STRONG> function does the
        following:
 
-       -    Obtains  the  number of wide characters pointed to by
-            <EM>wcval</EM>
+       <STRONG>o</STRONG>   Obtains  the  number  of wide characters pointed to by
+           <EM>wcval</EM>
 
-       -    Does not change  the  data  referenced  by  <EM>attrs</EM>  or
-            <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
+       <STRONG>o</STRONG>   Does not  change  the  data  referenced  by  <EM>attrs</EM>  or
+           <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
 
        The  <STRONG>setcchar</STRONG> function initializes the location pointed to
        by <EM>wcval</EM> by using:
 
-          The character attributes in <EM>attrs</EM>
+       <STRONG>o</STRONG>   The character attributes in <EM>attrs</EM>
 
-          The color pair in <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
+       <STRONG>o</STRONG>   The color pair in <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
 
-       -    The wide-character string pointed  to  by  <EM>wch</EM>.   The
-            string  must be L'\0' terminated, contain at most one
-            character with strictly positive width, which must be
-            the  first,  and  contain  no  characters of negative
-            width.
+       <STRONG>o</STRONG>   The wide-character string  pointed  to  by  <EM>wch</EM>.   The
+           string  must  be L'\0' terminated, contain at most one
+           spacing character, which must be the first.
+
+           Up to <STRONG>CCHARW_MAX</STRONG>-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.
 
 
 </PRE>
 <H2>NOTES</H2><PRE>
-       The <EM>opts</EM> argument is reserved for future use.   Currently,
+       The  <EM>opts</EM> argument is reserved for future use.  Currently,
        an application must provide a null pointer as <EM>opts</EM>.
 
-       The  <EM>wcval</EM>  argument may be a value generated by a call to
-       <STRONG>setcchar</STRONG> or by a function that has a <STRONG>cchar_t</STRONG> output  argu-
-       ment.   If  <EM>wcval</EM>  is  constructed by any other means, the
+       The <EM>wcval</EM> argument may be a value generated by a  call  to
+       <STRONG>setcchar</STRONG>  or by a function that has a <STRONG>cchar_t</STRONG> output argu-
+       ment.  If <EM>wcval</EM> is constructed by  any  other  means,  the
        effect is unspecified.
 
 
 </PRE>
-<H2>RETURN VALUES</H2><PRE>
+<H2>RETURN VALUE</H2><PRE>
        When <EM>wch</EM> is a null pointer, <STRONG>getcchar</STRONG> returns the number of
-       wide characters referenced by <EM>wcval</EM>.
+       wide characters referenced by <EM>wcval</EM>, including one  for  a
+       trailing null.
 
        When  <EM>wch</EM>  is not a null pointer, <STRONG>getcchar</STRONG> returns <STRONG>OK</STRONG> upon
        successful completion, and <STRONG>ERR</STRONG> otherwise.
 </PRE>
 <H2>SEE ALSO</H2><PRE>
        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>,
-       <STRONG><A HREF="wcwidth.3.html">wcwidth(3)</A></STRONG>.
+       <STRONG>wcwidth(3)</STRONG>.