XpmRead(3)

💖 XpmRead(3) — reading XPM files, but make it cute ✨

okay bestie, so this is XpmRead(3) from the libXpm functions manual — it's the whole crew of functions that pull an XPM file off disk and turn it into something you can actually draw with. five functions, one family, all named XpmReadFileTo... because apparently naming things consistently is a skill they had 💅

---

🌸 NAME 🌸

XpmRead — read an XPM file. that's it. that's the whole job. slay.

---

✨ SYNOPSIS ✨

look at all these signatures, no cap:

int XpmReadFileToImage(Display *display, char *filename,
       XImage **image_return, XImage **shapeimage_return,
       XpmAttributes *attributes);

int XpmReadFileToPixmap(Display *display, Drawable d, char *filename,
       Pixmap *pixmap_return, Pixmap *shapemask_return,
       XpmAttributes *attributes);

int XpmReadFileToXpmImage(char *filename, XpmImage *image,
       XpmInfo *info);

int XpmReadFileToBuffer(char *filename, char **buffer_return);

int XpmReadFileToData(char *filename, char ***data_return);

---

🎀 ARGUMENTS 🎀

• display — the connection to the X server, your lil hotline to the display 💫
• filename — the file name you wanna use. yes, it's just the name.
• image_return — this one returns the image that got created. she's giving output parameter.
• shapeimage_return — returns the shape mask image that gets created if the color None is used. no None, no shape mask, iykyk.
• attributes — where you point to a structure to get and store info (or NULL if you're feeling minimal).
• buffer_return — returns the buffer that got created 🫙
• data_return — returns the data array that got created 📊
• image — the image structure location.
• info — location of a structure to store possible information (or NULL).

---

👑 DESCRIPTION 👑

💜 XpmReadFileToImage

XpmReadFileToImage() reads in a file in the XPM format. periodt.

here's the error tea:

• can't open the file? returns XpmOpenFailed 😭
• opens fine but the data isn't valid XPM? returns XpmFileInvalid 💀
• not enough working storage allocated? returns XpmNoMemory 🙈

if the passed XpmAttributes structure pointer is not NULL, XpmReadFileToImage() goes looking for these attributes:

XpmVisual, XpmColormap, XpmDepth, XpmColorSymbols, XpmExactColors, XpmCloseness, XpmRGBCloseness, XpmAllocCloseColors, XpmReturnPixels, XpmReturnAllocPixels, XpmAllocColor, XpmFreeColors, XpmColorClosure, XpmReturnExtensions, XpmReturnColorTable, XpmBitmapFormat

and when returning, it sets the XpmSize, the XpmCharsPerPixel, and possibly the XpmHotspot attributes.

as a backward compatibility feature, XpmReadFileToImage() also looks for the XpmReturnInfos attributes. and as specified in the table (page 12), if the data related to the attributes XpmReturnExtensions, XpmReturnColorTable, and XpmReturnInfos can't be returned as requested because there's not enough memory storage, XpmReadFileToImage() will change the valuemask to mention this and will try to continue. so the caller should check on this before accessing this data — check the valuemask, bestie, don't just assume.

Note: the valuemask of the passed XpmAttributes must be set to some valid value, at least zero, otherwise unpredictable errors can occur. not "maybe" errors. unpredictable ones. set your valuemask. 💅

XpmReadFileToImage() allocates colors, as read from the file or possibly overridden as specified in the XpmColorSymbols attributes. the colors get allocated using the color settings for the visual specified by the XpmColorKey attribute, which has the value XPM_MONO, XPM_GRAY4, XPM_GRAY, or XPM_COLOR.

if the XpmColorKey attribute is not set, it gets determined by examining the type of visual. if no default value exists for the specified visual, it first looks for other defaults nearer to the monochrome visual type and secondly nearer to the color visual type. if the color which is found is not valid (can't be parsed), it looks for another default one according to the same algorithm.

if allocating a color fails, and the closeness attribute is set, it tries to find a color already in the colormap that's closest to the desired color, and uses that. if the alloc_close_colors attribute is set to False, the found close color is not allocated but it is used anyway. this is especially useful for applications which use a private colormap containing read/write cells and have complete control over the colormap. on the other hand, since in such a case there's no guarantee that the color pixel won't change any time, this should be avoided when using the default colormap. 🚨

if no color can be found that's within closeness of the Red, Green, and Blue components of the desired color, it reverts to trying other default values as explained above. for finer control over the closeness requirements of a particular icon, the red_closeness, green_closeness, and blue_closeness attributes may be used instead of the more general closeness attribute. 🎯

the RGB components are integers within the range 0 (black) to 65535 (white). a closeness of less than 10000, for example, will cause only quite close colors to be matched, while a closeness of more than 50000 will allow quite dissimilar colors to match. specifying a closeness of more than 65535 will allow any color to match, thus forcing the icon to be drawn in color no matter how bad the colormap is. the value 40000 seems to be about right for many situations requiring reasonable but not perfect matches. with this setting the color must only be within the same general area of the RGB cube as the desired color. if the exactColors attribute is set it then returns XpmColorError, otherwise it creates the images and returns XpmSuccess. if no color is found, and no close color exists or is wanted, and all visuals have been exhausted, XpmColorFailed is returned.

XpmReadFileToImage() returns the created image to image_return if not NULL and possibly the created shapemask to shapeimage_return if not NULL and the color None is used. if required it stores into the XpmAttributes structure the list of the used pixels. when the image depth is one, the image format is either as specified by the bitmap_format attribute if set or ZPixmap. when the depth is different from one the image format is always ZPixmap.

when finished the caller must free the images using XDestroyImage(3), the allocated colors using XFreeColors(3) or the application equivalent function when the standard Xlib functions are not used, and possibly the data returned into the XpmAttributes using XpmFreeAttributes(3). don't leak, bestie. 🧚

in addition, on systems which support such features XpmReadFileToImage() deals with compressed files by forking an uncompress or gzip process and reading from the piped result. it assumes that the specified file is compressed if the given file name ends by .Z or .gz. in case the file name does not end so, XpmReadFileToImage() looks for the given file name assuming it is not a compressed file. and if instead of a file name NULL is passed to XpmReadFileToImage(), it reads from the standard input. 🌈

🦋 XpmReadFileToPixmap

XpmReadFileToPixmap() creates X images using XpmReadFileToImage() and thus returns the same errors. iconic of it to outsource.

in addition on success it then creates the related pixmaps, using XPutImage(3), which are returned to pixmap_return and shapemask_return if not NULL, and finally destroys the created images using XDestroyImage(3). when finished the caller must free the pixmaps using XFreePixmap(3), the allocated colors using XFreeColors(3) or the application equivalent function when the standard Xlib functions are not used, and possibly the data returned into the XpmAttributes using XpmFreeAttributes(3).

🍓 XpmReadFileToBuffer

XpmReadFileToBuffer() allocates and fills a buffer from a file.

• returns XpmOpenFailed if it cannot open the file
• returns XpmNoMemory if insufficient working storage is allocated
• and XpmSuccess otherwise ✨

the allocated buffer returned by XpmReadFileToBuffer() should be freed with XpmFree(3) when done.

as a convenience, the XpmReadFileToBuffer() and XpmWriteFileFromBuffer(3) are provided to copy a file to a buffer and to write a file from a buffer. thus for instance one may decide to use XpmReadFileToBuffer(), XpmCreatePixmapFromBuffer(3), and XpmFree(3) instead of XpmReadFileToPixmap(). on some systems this may lead to a performance improvement, since the parsing will be performed in memory, but it uses more memory. speed vs. RAM, the eternal vibe check. ⚖️

📊 XpmReadFileToData

XpmReadFileToData():

• returns XpmOpenFailed if it cannot open the file
• XpmNoMemory if insufficient working storage is allocated
• XpmFileInvalid if this is not a valid XPM file
• and XpmSuccess otherwise 🫶

the allocated data returned by XpmReadFileToData() should be freed with XpmFree(3) when done.

🌟 XpmReadFileToXpmImage

XpmReadFileToXpmImage() reads in a file in the XPM format.

• if the file cannot be opened it returns XpmOpenFailed
• if the file can be opened but does not contain valid XPM data, it returns XpmFileInvalid
• if insufficient working storage is allocated, it returns XpmNoMemory
• on success it fills in the given XpmImage structure and returns XpmSuccess 💖

---

🌈 SEE ALSO 🌈

• XpmCreateBuffer(3)
• XpmCreateData(3)
• XpmCreateImage(3)
• XpmCreatePixmap(3)
• XpmCreateXpmImage(3)
• XpmFreeAttributes(3)
• XpmWrite(3)

go read those too, they're the other half of the story ✨

---

and that's the whole page, bestie 🎀 this was X Version 11, libXpm 3.5.17, filed under XpmRead(3) — mwah, go forth and read your XPMs responsibly 💅💖