XAllocColor()															     XAllocColor()

Name
  XAllocColor - allocate a read-only colormap cell with closest hardware-supported color.

Synopsis
  Status XAllocColor(display, colormap, colorcell_in_out)
	Display *display;
	Colormap colormap;
	XColor *colorcell_in_out;

Arguments
  display  Specifies a connection to an X server; returned from XOpenDisplay().

  colormap
	   Specifies the ID of the colormap in which the colorcell is to be allocated.

  colorcell_in_out
	   Specifies desired RGB values, and also returns the pixel value and the RGB values actually used in the colormap.

Returns
  Zero on failure, non-zero on success.

Description
  XAllocColor() returns the pixel value of a read-only (shareable) colorcell.  The requested RGB values are placed in colorcell_in_out, which
  is also used to return the allocated pixel value and the actual RGB values of that colorcell.  If XAllocColor() succeeds, it	returns  non-
  zero.  If it fails, it returns zero.

  XAllocColor()  acts  differently on static and dynamic visuals.  On PseudoColor, DirectColor, and GrayScale visuals, XAllocColor() fails if
  there are no unallocated colorcells and no allocated read-only cell exactly matches the requested RGB values.  On  StaticColor,  TrueColor,
  and StaticGray visuals, XAllocColor() returns the closest RGB values available in the colormap.  The colorcell_in_out structure returns the
  actual RGB values allocated.

  XAllocColor() does not use or affect the flags member of the XColor structure.

  For more information, see Volume One, Chapter 7, Color.

Structures
     typedef struct {
	 unsigned long pixel;
	 unsigned short red, green, blue;
	 char flags;	/* DoRed, DoGreen, DoBlue */
	 char pad;
     } XColor;

Errors
  BadColor  colormap is invalid.

See Also
  XBlackPixel(), XWhitePixel(), XAllocColorCells(), XAllocColorPlanes(), XAllocNamedColor(),  XFreeColors(),  XLookupColor(),  XParseColor(),
  XQueryColor(), XQueryColors(), XStoreColor(), XStoreColors(), XStoreNamedColor().

Xlib - Color Cells														     XAllocColor()