XINERAMA(3)

💖 XINERAMA(3) 💖

okay bestie, so this is the Xinerama library manual page, part of the X11 library functions family, and it's basically the ✨glow-up✨ API for the Xinerama extension to the X11 Protocol. sit with me, we're gonna get you fluent. 🦋

---

✨ NAME ✨

Xinerama — the API for the Xinerama extension to the X11 Protocol. that's it, that's the whole vibe. 💅

---

🎀 SYNOPSIS 🎀

first things first, you gotta pull in the header, no cap:

#include <X11/extensions/Xinerama.h>

then here come the four functions, and yes they're giving main character energy:

Bool XineramaQueryExtension (Display *dpy,
     int *event_base_return, int *error_base_return);

Status XineramaQueryVersion (Display *dpy,
     int *major_version_return,
     int *minor_version_return);

Bool XineramaIsActive (Display *dpy);

XineramaScreenInfo * XineramaQueryScreens (Display *dpy,
     int *number);

literally copy these exactly, don't freestyle the signatures, i'm begging 🫶

---

🌸 ARGUMENTS 🌸

here's the cast of characters, everyone plays a role:

• display — specifies the connection to the X server. it's your link to the whole situation. 🔗
• event_base_return — the spot where the assigned base event code gets returned. 📥
• error_base_return — the spot where the assigned base error code gets returned. 📥
• major_version_return — returns the major version that the server supports.
• minor_version_return — returns the minor version that the server supports.
• number — returns how many entries are in the XineramaScreenInfo array you get back. count 'em, bestie. 🔢

---

💜 DESCRIPTION 💜

so Xinerama is a simple library — and like, genuinely simple, not "simple" in the way people describe a 400-line shell script — designed to interface the Xinerama Extension. its whole job? retrieving information about physical output devices that may be combined into a single logical X screen. yes queen, multiple monitors, one screen, we love to see it. 🖥️🖥️➡️🖥️

---

👑 FUNCTIONS 👑

🔍 XineramaQueryExtension()

this one queries the X server to figure out whether the Xinerama Extension is even available. like a vibe check but for protocol extensions.

• if the extension is available: the return value is True, and event_base_return and error_base_return get set to the base event number and base error number for the extension, respectively. slay. ✅
• otherwise: the return value is False, and the values of event_base_return and error_base_return are undefined.

⚠️ bestie, pay attention to that last bit: undefined. do NOT go reading those out params when you got a False back. that's not a vibe, that's undefined behavior territory. 💀

🔍 XineramaQueryVersion()

this one returns the version of the Xinerama extension that the X server has implemented. the version lands in major_version_return and minor_version_return.

here's the versioning tea ☕:

• the major version gets incremented for protocol incompatible changes — big changes, break-y changes.
• the minor version gets incremented for small, upwardly compatible changes — lil baby changes, everyone's fine.

and the return value?

• if the Xinerama library is compatible with the version the server returned, it returns nonzero.
• it returns zero if: the server doesn't support the XINERAMA extension, or there was an error during communications with the server, or the server and library protocol versions are incompatible. 😭

🔍 XineramaIsActive()

returns a Boolean operator used to determine if Xinerama is activated on the screen. that's it, that's the function. True for active, False for not active. short, sweet, iconic. ✨

🔍 XineramaQueryScreens()

the big one. this returns info about each individual output device within the Xinerama Screen.

the integer that number points to gets updated to the number of output devices listed in the returned array of XineramaScreenInfo structures. so you hand it a pointer, it fills in the count. teamwork. 🫶

and if Xinerama is not active? it returns NULL and sets number to 0. not a crash, just an empty party. 🙈

🧚 IMPORTANT: the pointer you get back should be released with XFree(3) when it's no longer needed. free your memory, bestie, it's the responsible thing to do. don't leak, it's not cute.

---

📌 NOTE 📌

the original API for interacting with the XINERAMA extension used function names beginning with XPanoramiX. that API is now deprecated — it's giving legacy, it's giving "we don't do that anymore" — and this API should be used instead in new software. so if you're writing something new, use this one. periodt. 💅

---

🌈 and that's the whole page, bestie 🌈

you made it to the end, i'm so proud of you, genuinely. this was libXinerama 1.1.5 out of the X Version 11 crew, and if you remember nothing else, remember: check the extension first, mind your undefined values, and always XFree(3) your pointers. mwah. 😘💖

X Version 11 · libXinerama 1.1.5 · XINERAMA(3) — byeeee 🎀✨🦋