ncurses 6.0 - patch 20170401
[ncurses.git] / doc / html / man / curs_color.3x.html
index 843ada75166d51757100ad395a7083bc855ff9f3..bab33b328c15d3f8d2d0aa4c86ba319188932f52 100644 (file)
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_color.3x,v 1.47 2017/03/13 21:49:37 tom Exp @
-  * .br
-  * .br
-  * .br
+  * @Id: curs_color.3x,v 1.50 2017/04/01 19:57:19 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
@@ -49,8 +46,8 @@
 
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
-       <STRONG>start_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>color_content</STRONG>,
-       <STRONG>pair_content</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>COLOR_PAIR</STRONG>,
+       <STRONG>start_color</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>init_pair</STRONG>,
+       <STRONG>init_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>,
        <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> color manipulation routines
 
 
 
        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
 
+       <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
+       <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
        <STRONG>int</STRONG> <STRONG>init_color(short</STRONG> <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>r,</STRONG> <STRONG>short</STRONG> <STRONG>g,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
+       /* extensions */
+       <STRONG>int</STRONG> <STRONG>init_extended_pair(int</STRONG> <STRONG>pair,</STRONG> <STRONG>int</STRONG> <STRONG>f,</STRONG> <STRONG>int</STRONG> <STRONG>b);</STRONG>
+       <STRONG>int</STRONG> <STRONG>init_extended_color(int</STRONG> <STRONG>color,</STRONG> <STRONG>int</STRONG> <STRONG>r,</STRONG> <STRONG>int</STRONG> <STRONG>g,</STRONG> <STRONG>int</STRONG> <STRONG>b);</STRONG>
 
        <STRONG>int</STRONG>  <STRONG>color_content(short</STRONG>  <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>*r,</STRONG> <STRONG>short</STRONG> <STRONG>*g,</STRONG> <STRONG>short</STRONG>
        <STRONG>*b);</STRONG>
        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
-
-       <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
-       <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
+       /* extensions */
+       <STRONG>int</STRONG> <STRONG>extended_color_content(int</STRONG> <STRONG>color,</STRONG> <STRONG>int</STRONG> <STRONG>*r,</STRONG> <STRONG>int</STRONG> <STRONG>*g,</STRONG>  <STRONG>int</STRONG>
+       <STRONG>*b);</STRONG>
+       <STRONG>int</STRONG> <STRONG>extended_pair_content(int</STRONG> <STRONG>pair,</STRONG> <STRONG>int</STRONG> <STRONG>*f,</STRONG> <STRONG>int</STRONG> <STRONG>*b);</STRONG>
 
        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <STRONG>n);</STRONG>
        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
-       <STRONG>curses</STRONG> supports color attributes on  terminals  with  that
-       capability.   To  use  these  routines <STRONG>start_color</STRONG> must be
-       called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
-       used  in pairs (referred to as color-pairs).  A color-pair
-       consists of a foreground  color  (for  characters)  and  a
+       <STRONG>curses</STRONG>  supports  color  attributes on terminals with that
+       capability.  To use these  routines  <STRONG>start_color</STRONG>  must  be
+       called,  usually  right  after <STRONG>initscr</STRONG>.  Colors are always
+       used in pairs (referred to as color-pairs).  A  color-pair
+       consists  of  a  foreground  color  (for characters) and a
        background color (for the blank field on which the charac-
-       ters are displayed).  A programmer  initializes  a  color-
-       pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
+       ters  are  displayed).   A programmer initializes a color-
+       pair with the routine <STRONG>init_pair</STRONG>.  After it has  been  ini-
        tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to convert the pair to
        a video attribute.
 
-       If  a  terminal  is capable of redefining colors, the pro-
+       If a terminal is capable of redefining  colors,  the  pro-
        grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
-       nition   of   a   color.    The  routines  <STRONG>has_colors</STRONG>  and
-       <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,  depending   on
-       whether  the  terminal  has color capabilities and whether
-       the programmer can change the colors.   The  routine  <STRONG>col-</STRONG>
-       <STRONG>or_content</STRONG>  allows  a programmer to extract the amounts of
-       red, green, and blue components in an  initialized  color.
-       The  routine  <STRONG>pair_content</STRONG> allows a programmer to find out
+       nition  of  a  color.    The   routines   <STRONG>has_colors</STRONG>   and
+       <STRONG>can_change_color</STRONG>   return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,  depending  on
+       whether the terminal has color  capabilities  and  whether
+       the  programmer  can  change the colors.  The routine <STRONG>col-</STRONG>
+       <STRONG>or_content</STRONG> allows a programmer to extract the  amounts  of
+       red,  green,  and blue components in an initialized color.
+       The routine <STRONG>pair_content</STRONG> allows a programmer to  find  out
        how a given color-pair is currently defined.
 
 
 </PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
-       The <STRONG>curses</STRONG> library combines these inputs  to  produce  the
-       actual  foreground  and  background  colors  shown  on the
+       The  <STRONG>curses</STRONG>  library  combines these inputs to produce the
+       actual foreground  and  background  colors  shown  on  the
        screen:
 
        <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
 
        <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
 
-       Per-character and window attributes are usually set  by  a
-       parameter  containing  video  attributes including a color
-       pair value.  Some functions such as <STRONG>wattr_set</STRONG> use a  sepa-
+       Per-character  and  window attributes are usually set by a
+       parameter containing video attributes  including  a  color
+       pair  value.  Some functions such as <STRONG>wattr_set</STRONG> use a sepa-
        rate parameter which is the color pair number.
 
-       The  background character is a special case: it includes a
+       The background character is a special case: it includes  a
        character value, just as if it were passed to <STRONG>waddch</STRONG>.
 
        The <STRONG>curses</STRONG> library does the actual work of combining these
            <STRONG>o</STRONG>   <STRONG>curses</STRONG> next checks the window attribute.
 
            <STRONG>o</STRONG>   If the window attribute does not use color pair 0,
-               <STRONG>curses</STRONG>  uses  the  color  pair from the window at-
+               <STRONG>curses</STRONG> uses the color pair  from  the  window  at-
                tribute.
 
            <STRONG>o</STRONG>   Otherwise, <STRONG>curses</STRONG> uses the background character.
 
-       <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or  it
-           does  not use the special color pair 0, <STRONG>curses</STRONG> prefers
-           the color pair from the parameter, if it  is  nonzero.
+       <STRONG>o</STRONG>   If  the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it
+           does not use the special color pair 0, <STRONG>curses</STRONG>  prefers
+           the  color  pair from the parameter, if it is nonzero.
            Otherwise, it tries the window attribute next, and fi-
            nally the background character.
 
-       Some <STRONG>curses</STRONG> functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>.   Those
-       do  not  combine  its parameter with a color pair.  Conse-
-       quently those calls use only the window attribute  or  the
+       Some  <STRONG>curses</STRONG> functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>.  Those
+       do not combine its parameter with a  color  pair.   Conse-
+       quently  those  calls use only the window attribute or the
        background character.
 
 
-</PRE><H3><a name="h3-Routine-Descriptions">Routine Descriptions</a></H3><PRE>
+</PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
+       In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
+       the  standard colors (ISO-6429).  <STRONG>curses</STRONG> also assumes that
+       <STRONG>COLOR_BLACK</STRONG> is the default background color for all termi-
+       nals.
+
+             <STRONG>COLOR_BLACK</STRONG>
+             <STRONG>COLOR_RED</STRONG>
+             <STRONG>COLOR_GREEN</STRONG>
+             <STRONG>COLOR_YELLOW</STRONG>
+             <STRONG>COLOR_BLUE</STRONG>
+             <STRONG>COLOR_MAGENTA</STRONG>
+             <STRONG>COLOR_CYAN</STRONG>
+             <STRONG>COLOR_WHITE</STRONG>
+
+       Some terminals support more than the eight (8) "ANSI" col-
+       ors.  There are no standard  names  for  those  additional
+       colors.
+
+
+</PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
+
+</PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
+       is  initialized  by  <STRONG>start_color</STRONG>  to the maximum number of
+       colors the terminal can support.
+
+
+</PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
+       is initialized by <STRONG>start_color</STRONG> to  the  maximum  number  of
+       color pairs the terminal can support.
+
+
+</PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
+
+</PRE><H3><a name="h3-start_color">start_color</a></H3><PRE>
        The <STRONG>start_color</STRONG> routine requires no arguments.  It must be
        called if the programmer wants to use colors,  and  before
        any  other  color  manipulation  routine is called.  It is
        a runtime error:
 
        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_col-</STRONG>
-           <STRONG>ors</STRONG> capability, which is typically a signed 16-bit in-
-           teger (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
+           <STRONG>ors</STRONG> capability, (see <STRONG><A HREF="max_colterminfo.5.html">terminfo(5)</A></STRONG>).
 
        <STRONG>o</STRONG>   color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
            <STRONG>ORS-1</STRONG>, inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
 
-       <STRONG>o</STRONG>   a  special  color value <STRONG>-1</STRONG> is used in certain extended
-           functions to denote the  <EM>default</EM>  <EM>color</EM>  (see  <STRONG>use_de-</STRONG>
+       <STRONG>o</STRONG>   a special color value <STRONG>-1</STRONG> is used in  certain  extended
+           functions  to  denote  the  <EM>default</EM> <EM>color</EM> (see <STRONG>use_de-</STRONG>
            <STRONG>fault_colors</STRONG>).
 
-       <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds  to  the  terminal database's
-           <STRONG>max_pairs</STRONG> capability,  which  is  typically  a  signed
-           16-bit integer (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
+       <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG> corresponds  to  the  terminal  database's
+           <STRONG>max_pairs</STRONG> capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 
        <STRONG>o</STRONG>   legal  color  pair  values  are in the range <STRONG>1</STRONG> to <STRONG>COL-</STRONG>
            <STRONG>OR_PAIRS-1</STRONG>, inclusive.
            is initialized.  It cannot be modified by the applica-
            tion.
 
+
+</PRE><H3><a name="h3-has_colors">has_colors</a></H3><PRE>
+       The  <STRONG>has_colors</STRONG> routine requires no arguments.  It returns
+       <STRONG>TRUE</STRONG> if the terminal can manipulate colors; otherwise,  it
+       returns <STRONG>FALSE</STRONG>.  This routine facilitates writing terminal-
+       independent programs.  For example, a programmer  can  use
+       it  to decide whether to use color or some other video at-
+       tribute.
+
+
+</PRE><H3><a name="h3-can_change_color">can_change_color</a></H3><PRE>
+       The <STRONG>can_change_color</STRONG> routine requires  no  arguments.   It
+       returns  <STRONG>TRUE</STRONG>  if  the  terminal  supports  colors and can
+       change their definitions; other, it returns  <STRONG>FALSE</STRONG>.   This
+       routine facilitates writing terminal-independent programs.
+
+
+</PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
        The  <STRONG>init_pair</STRONG>  routine changes the definition of a color-
        pair.  It takes three arguments: the number of the  color-
        pair  to  be changed, the foreground color number, and the
        changed to the new definition.
 
        As  an  extension,  ncurses allows you to set color pair <STRONG>0</STRONG>
-       via the <STRONG>assume_default_colors</STRONG> routine, or to  specify  the
-       use  of  default colors (color number <STRONG>-1</STRONG>) if you first in-
-       voke the <STRONG>use_default_colors</STRONG> routine.
+       via the <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or  to  specify
+       the  use  of default colors (color number <STRONG>-1</STRONG>) if you first
+       invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> routine.
+
 
+</PRE><H3><a name="h3-init_color">init_color</a></H3><PRE>
        The <STRONG>init_color</STRONG> routine changes the definition of a  color.
        It  takes  four  arguments:  the number of the color to be
        changed followed by three RGB values (for the  amounts  of
-       red, green, and blue components).  The first argument must
-       be a legal color value; default  colors  are  not  allowed
-       here.   (See  the section <STRONG>Colors</STRONG> for the default color in-
-       dex.)  Each of the last three arguments must be a value in
-       the  range  <STRONG>0</STRONG>  through <STRONG>1000</STRONG>.  When <STRONG>init_color</STRONG> is used, all
-       occurrences of that color on the screen immediately change
-       to the new definition.
+       red, green, and blue components).
 
-       The  <STRONG>has_colors</STRONG> routine requires no arguments.  It returns
-       <STRONG>TRUE</STRONG> if the terminal can manipulate colors; otherwise,  it
-       returns <STRONG>FALSE</STRONG>.  This routine facilitates writing terminal-
-       independent programs.  For example, a programmer  can  use
-       it  to decide whether to use color or some other video at-
-       tribute.
+       <STRONG>o</STRONG>   The  first  argument  must be a legal color value; de-
+           fault colors are not allowed here.  (See  the  section
+           <STRONG>Colors</STRONG> for the default color index.)
+
+       <STRONG>o</STRONG>   Each  of  the  last three arguments must be a value in
+           the range <STRONG>0</STRONG> through <STRONG>1000</STRONG>.
+
+       When <STRONG>init_color</STRONG> is used, all occurrences of that color  on
+       the screen immediately change to the new definition.
 
-       The <STRONG>can_change_color</STRONG> routine requires  no  arguments.   It
-       returns  <STRONG>TRUE</STRONG>  if  the  terminal  supports  colors and can
-       change their definitions; other, it returns  <STRONG>FALSE</STRONG>.   This
-       routine facilitates writing terminal-independent programs.
 
+</PRE><H3><a name="h3-color_content">color_content</a></H3><PRE>
        The  <STRONG>color_content</STRONG> routine gives programmers a way to find
        the intensity of the red, green, and blue (RGB) components
        in a color.  It requires four arguments: the color number,
        and three addresses of <STRONG>short</STRONG>s for storing the  information
        about  the  amounts  of red, green, and blue components in
-       the given color.  The first argument must be a legal color
-       value,  i.e.,  <STRONG>0</STRONG>  through <STRONG>COLORS-1</STRONG>, inclusive.  The values
-       that are stored at the addresses pointed to  by  the  last
-       three  arguments are in the range <STRONG>0</STRONG> (no component) through
-       <STRONG>1000</STRONG> (maximum amount of component), inclusive.
+       the given color.
 
+       <STRONG>o</STRONG>   The first argument must be a legal color value,  i.e.,
+           <STRONG>0</STRONG> through <STRONG>COLORS-1</STRONG>, inclusive.
+
+       <STRONG>o</STRONG>   The values that are stored at the addresses pointed to
+           by the last three arguments are in  the  range  <STRONG>0</STRONG>  (no
+           component) through <STRONG>1000</STRONG> (maximum amount of component),
+           inclusive.
+
+
+</PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
        The <STRONG>pair_content</STRONG> routine allows programmers  to  find  out
        what  colors  a given color-pair consists of.  It requires
        three arguments: the color-pair number, and two  addresses
        of  <STRONG>short</STRONG>s  for  storing the foreground and the background
-       color numbers.  The first argument must be a  legal  color
-       value,  i.e., in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclu-
-       sive.  The values that are stored at the addresses pointed
-       to  by  the  second and third arguments are in the range <STRONG>0</STRONG>
-       through <STRONG>COLORS</STRONG>, inclusive.
+       color numbers.
 
-       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) extracts the color value from its <EM>attrs</EM>
-       parameter  and returns it as a color pair number.  Its in-
-       verse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an at-
-       tribute.   Attributes  can hold color pairs in the range 0
-       to 255.  If you need a color pair larger  than  that,  you
-       must  use functions such as <STRONG>attr_set</STRONG> (which pass the color
-       pair as a separate parameter) rather than the legacy func-
-       tions such as <STRONG>attrset</STRONG>.
+       <STRONG>o</STRONG>   The first argument must be a legal color value,  i.e.,
+           in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 
+       <STRONG>o</STRONG>   The values that are stored at the addresses pointed to
+           by the second and third arguments are in the  range  <STRONG>0</STRONG>
+           through <STRONG>COLORS</STRONG>, inclusive.
 
-</PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
-       In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
-       the standard colors (ISO-6429).  <STRONG>curses</STRONG> also assumes  that
-       <STRONG>COLOR_BLACK</STRONG> is the default background color for all termi-
-       nals.
 
-             <STRONG>COLOR_BLACK</STRONG>
-             <STRONG>COLOR_RED</STRONG>
-             <STRONG>COLOR_GREEN</STRONG>
-             <STRONG>COLOR_YELLOW</STRONG>
-             <STRONG>COLOR_BLUE</STRONG>
-             <STRONG>COLOR_MAGENTA</STRONG>
-             <STRONG>COLOR_CYAN</STRONG>
-             <STRONG>COLOR_WHITE</STRONG>
+</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
+       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) extracts the color value from its <EM>attrs</EM>
+       parameter and returns it as a color pair number.
+
+
+</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
+       Its inverse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number  to
+       an  attribute.   Attributes  can  hold  color pairs in the
+       range 0 to 255.  If you need  a  color  pair  larger  than
+       that,  you must use functions such as <STRONG>attr_set</STRONG> (which pass
+       the color pair as a separate parameter)  rather  than  the
+       legacy functions such as <STRONG>attrset</STRONG>.
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-       The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG>  return  <STRONG>TRUE</STRONG>
+       The  routines  <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG>
        or <STRONG>FALSE</STRONG>.
 
        All other routines return the integer <STRONG>ERR</STRONG> upon failure and
-       an <STRONG>OK</STRONG> (SVr4 specifies only "an integer  value  other  than
+       an  <STRONG>OK</STRONG>  (SVr4  specifies only "an integer value other than
        <STRONG>ERR</STRONG>") upon successful completion.
 
-       X/Open  defines  no error conditions.  This implementation
-       will return <STRONG>ERR</STRONG> on attempts to use  color  values  outside
-       the range <STRONG>0</STRONG> to COLORS-1 (except for the default colors ex-
-       tension), or use color pairs outside the range <STRONG>0</STRONG>  to  <STRONG>COL-</STRONG>
-       <STRONG>OR_PAIRS-1</STRONG>.   Color  values  used in <STRONG>init_color</STRONG> must be in
-       the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all  func-
-       tions  if the terminal has not been initialized.  An error
-       is returned from secondary functions such as <STRONG>init_pair</STRONG>  if
+       X/Open defines no error conditions.   This  implementation
+       will  return  <STRONG>ERR</STRONG>  on attempts to use color values outside
+       the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1 (except for the default colors ex-
+       tension),  or  use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
+       <STRONG>OR_PAIRS-1</STRONG>.  Color values used in <STRONG>init_color</STRONG>  must  be  in
+       the  range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all func-
+       tions if the terminal has not been initialized.  An  error
+       is  returned from secondary functions such as <STRONG>init_pair</STRONG> if
        <STRONG>start_color</STRONG> was not called.
 
           <STRONG>init_color</STRONG>
-               returns  an error if the terminal does not support
-               this feature, e.g., if the <STRONG>initialize_color</STRONG>  capa-
+               returns an error if the terminal does not  support
+               this  feature, e.g., if the <STRONG>initialize_color</STRONG> capa-
                bility is absent from the terminal description.
 
           <STRONG>start_color</STRONG>
-               returns  an error if the color table cannot be al-
+               returns an error if the color table cannot be  al-
                located.
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
-       In the <STRONG>ncurses</STRONG> implementation, there is a  separate  color
+       In  the  <STRONG>ncurses</STRONG> implementation, there is a separate color
        activation flag, color palette, color pairs table, and as-
-       sociated COLORS and COLOR_PAIRS counts  for  each  screen;
-       the  <STRONG>start_color</STRONG> function only affects the current screen.
+       sociated  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG> counts for each screen;
+       the <STRONG>start_color</STRONG> function only affects the current  screen.
        The SVr4/XSI interface is not really designed with this in
-       mind,  and  historical  implementations  may  use a single
+       mind, and historical  implementations  may  use  a  single
        shared color palette.
 
-       Note that setting an implicit background color via a color
-       pair  affects  only character cells that a character write
-       operation explicitly touches.  To  change  the  background
-       color  used  when parts of a window are blanked by erasing
-       or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
+       Setting  an implicit background color via a color pair af-
+       fects only character cells that a character  write  opera-
+       tion  explicitly  touches.  To change the background color
+       used when parts of a window  are  blanked  by  erasing  or
+       scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 
-       Several caveats apply on 386 and 486  machines  with  VGA-
-       compatible graphics:
+       Several  caveats  apply on older x86 machines (e.g., i386,
+       i486) with VGA-compatible graphics:
 
-       <STRONG>o</STRONG>   COLOR_YELLOW  is  actually  brown.  To get yellow, use
+       <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To  get  yellow,  use
            COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
 
        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the back-
-           ground  to  go  bright.  This often fails to work, and
+           ground to go bright.  This often fails  to  work,  and
            even some cards for which it mostly works (such as the
-           Paradise  and compatibles) do the wrong thing when you
-           try to set a bright "yellow"  background  (you  get  a
+           Paradise and compatibles) do the wrong thing when  you
+           try  to  set  a  bright "yellow" background (you get a
            blinking yellow foreground instead).
 
        <STRONG>o</STRONG>   Color RGB values are not settable.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-       This  implementation  satisfies XSI Curses's minimum maxi-
+       This implementation satisfies XSI Curses's  minimum  maxi-
        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
 
-       The <STRONG>init_pair</STRONG> routine accepts  negative  values  of  fore-
-       ground   and  background  color  to  support  the  <STRONG>use_de-</STRONG>
-       <STRONG>fault_colors</STRONG> extension, but only if that routine has  been
-       first invoked.
+       The  <STRONG>init_pair</STRONG>  routine  accepts  negative values of fore-
+       ground  and  background  color  to  support  the   <STRONG>use_de-</STRONG>
+       <STRONG><A HREF="use_default_colors.3x.html">fault_colors(3x)</A></STRONG>  extension,  but only if that routine has
+       been first invoked.
 
-       The  assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
-       color for all terminals can  be  modified  using  the  <STRONG>as-</STRONG>
-       <STRONG>sume_default_colors</STRONG> extension.
+       The assumption that <STRONG>COLOR_BLACK</STRONG> is the default  background
+       color  for  all  terminals  can  be modified using the <STRONG>as-</STRONG>
+       <STRONG><A HREF="assume_default_colors.3x.html">sume_default_colors(3x)</A></STRONG> extension.
 
-       This  implementation  checks  the  pointers, e.g., for the
-       values returned by  <STRONG>color_content</STRONG>  and  <STRONG>pair_content</STRONG>,  and
+       This implementation checks the  pointers,  e.g.,  for  the
+       values  returned  by  <STRONG>color_content</STRONG>  and <STRONG>pair_content</STRONG>, and
        will treat those as optional parameters when null.
 
+       X/Open Curses does not specify a limit for the  number  of
+       colors and color pairs which a terminal can support.  How-
+       ever, in its use of <STRONG>short</STRONG> for the parameters,  it  carries
+       over SVr4's implementation detail for the compiled termin-
+       fo database, which uses signed 16-bit numbers.   This  im-
+       plementation provides extended versions of those functions
+       which use <STRONG>short</STRONG> parameters, allowing applications  to  use
+       larger color- and pair-numbers.
+
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,  <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  <STRONG>curs_vari-</STRONG>
 <ul>
 <li><a href="#h3-Overview">Overview</a></li>
 <li><a href="#h3-Color-Rendering">Color Rendering</a></li>
-<li><a href="#h3-Routine-Descriptions">Routine Descriptions</a></li>
-<li><a href="#h3-Colors">Colors</a></li>
+</ul>
+</li>
+<li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
+<li><a href="#h2-VARIABLES">VARIABLES</a>
+<ul>
+<li><a href="#h3-COLORS">COLORS</a></li>
+<li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
+</ul>
+</li>
+<li><a href="#h2-FUNCTIONS">FUNCTIONS</a>
+<ul>
+<li><a href="#h3-start_color">start_color</a></li>
+<li><a href="#h3-has_colors">has_colors</a></li>
+<li><a href="#h3-can_change_color">can_change_color</a></li>
+<li><a href="#h3-init_pair">init_pair</a></li>
+<li><a href="#h3-init_color">init_color</a></li>
+<li><a href="#h3-color_content">color_content</a></li>
+<li><a href="#h3-pair_content">pair_content</a></li>
+<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
+<li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>