XpmWrite(3)

💖 XpmWrite — writing your XPMs to disk, bestie 💖

okay so this is XpmWrite from libXpm, section 3 of the manual. it's the whole little family of functions that take your pixmaps, images, buffers and data arrays and ✨*write them out*✨ as XPM files. no cap, it's giving "export button" energy. let's get into it 🫶

---

✨ SYNOPSIS ✨

int XpmWriteFileFromPixmap(Display *display, char *filename,
       Pixmap pixmap, Pixmap shapemask, XpmAttributes *attributes);

int XpmWriteFileFromImage(Display *display , char *filename,
       XImage *image, XImage *shapeimage, XpmAttributes *attributes);

int XpmWriteFileFromData(char *filename, char **data);

int XpmWriteFileFromXpmImage(char *filename, XpmImage *image,
       XImage *shapeimage, XpmInfo *info);

int XpmWriteFileFromBuffer(char *filename, char *buffer);

---

🌸 ARGUMENTS 🌸

• display — the connection to the X server, literally just the plug into your X session 🔌
• filename — the file name to use. yes, that one. the name of the file. 💅
• pixmap — the pixmap. she's the star of the show 👑
• shapemask — the shape mask pixmap, aka the little silhouette that says which bits are actually visible 🎀
• attributes — where a structure full of information lives (or NULL, if you're feeling minimal) ✨
• data — the data array to read 📖
• image — the image 🖼️
• info — where a structure to get information from lives (or NULL) 📋
• buffer — the buffer to read 🧺

---

💜 DESCRIPTION 💜

🦋 XpmWriteFileFromImage

XpmWriteFileFromImage() writes an image and its possible shapeimage out to a file in the XPM format. iconic behaviour honestly.

if the file cannot be opened, it returns XpmOpenFailed 😭. if insufficient working storage is allocated, it returns XpmNoMemory 💀. if no error occurs then it returns XpmSuccess 🎉.

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

• XpmColormap
• XpmHotspot
• XpmCharsPerPixel
• XpmRgbFilename
• XpmExtensions

and as a backward compatibility feature, XpmWriteFileFromImage() also looks for the XpmInfos attributes. the more you know 🌈

if the filename contains an extension such as “.xpm”, in order to get a valid C variable name, the dot character is replaced by an underscore '_' when writing out. yes bestie, the dot gets glow-upped into an underscore, it's a whole transformation ✨

as a backward compatibility feature, if the XpmInfos attributes are defined it writes out possible stored information such as comments, color defaults and symbol. 📝

finally, if the XpmRgbFilename attribute is defined, XpmWriteFileFromImage() searches for color names in this file and if found writes them out instead of the rgb values. so fancy 🎨

in addition, on systems which support such features: if the given file name ends by '.Z' or '.gz' it is assumed to be a compressed file. then XpmWriteFileFromImage() writes to a piped compress or gzip process. and if instead of a file name, NULL is passed to XpmWriteFileFromImage(), it writes to the standard output. the way that it just pipes itself, no cap 🔥

🧚 XpmWriteFileFromPixmap

to write out a Pixmap to an XPM file, use XpmWriteFileFromPixmap(). simple as that 💖

if the passed XpmAttributes structure pointer is not NULL, XpmWriteFileFromPixmap() looks for the following attribute: XpmSize. if it's not defined, it performs an XGetGeometry operation. then it uses XGetImage to get from the given pixmaps the related X images which are passed to XpmWriteFileFromImage(). finally XpmWriteFileFromPixmap() destroys the created images using XDestroyImage. clean up after yourself, periodt 🧹

the XpmWriteFileFromPixmap() function returns the same errors as XpmWriteFileFromImage().

🍓 XpmWriteFileFromData

XpmWriteFileFromData() writes an XPM data array to an XPM file.

XpmWriteFileToData() returns XpmOpenFailed if it cannot open the file, XpmFileInvalid if this is not a valid XPM data, and XpmSuccess otherwise.

🌈 XpmWriteFileFromXpmImage

to write out an XpmImage to an XPM file, use XpmWriteFileFromXpmImage(). the XpmWriteFileFromXpmImage() function writes an image out to a file in the XPM format.

if the file cannot be opened, it returns XpmOpenFailed 😭. if insufficient working storage is allocated, it returns XpmNoMemory 💀. if no error occurs then it returns XpmSuccess 🎉.

if the passed XpmInfo structure pointer is not NULL, XpmWriteFileFromXpmImage() looks for these attributes:

• XpmComments
• XpmExtensions
• XpmHotspot

and writes the related information out as well 📝.

in addition, on systems which support such features: if the given file name ends by '.Z' or '.gz' it is assumed to be a compressed file. then XpmWriteFileFromXpmImage() writes to a piped compress or gzip process. and if instead of a file name, NULL is passed to XpmWriteFileFromXpmImage(), it writes to the standard output 🌟

🎀 XpmWriteFileFromBuffer

XpmWriteFileFromBuffer() writes a XPM buffer to a file. XpmWriteFileFromBuffer() returns XpmOpenFailed if it cannot open the file, and XpmSuccess otherwise.

as a convenience, the XpmReadFileToBuffer() and XpmWriteFileFromBuffer() functions 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 XpmCreateBufferFromPixmap(), XpmWriteFileFromBuffer(), and XpmFree() instead of XpmWriteFileFromPixmap(). on some systems this may lead to a performance improvement, since the parsing will be performed in memory, but it uses more memory. highkey a tradeoff, you gotta pick your vibe ⚖️

---

👑 SEE ALSO 👑

• XpmRead(3)

---

that's the whole thing bestie, you're officially an XPM-writing main character now 💅✨ go forth and write those files. this was X Version 11, libXpm 3.5.17, from the XpmWrite(3) page — ily, bye 🫶💖🌸