XISELECTEVENTS(3)

💖 XISELECTEVENTS 💖

okay bestie, sit down, hydrate, and let me tell you about XISelectEvents and XIGetSelectedEvents — they're the girlies that let you select for or get selected XI2 events on a window. yes, this is a section 3 (library functions) situation, and yes, we're gonna get through it together. 🫶

---

✨ NAME ✨

XISelectEvents, XIGetSelectedEvents — select for or get selected XI2 events on the window. that's the whole vibe. that's the mission statement. 💅

---

🌸 SYNOPSIS 🌸

#include <X11/extensions/XInput2.h>

Status XISelectEvents( Display *display,
                       Window win,
                       XIEventMask *masks,
                       int num_masks);

display — Specifies the connection to the X server. (your link to the mothership, no cap)

masks — Device event mask.

num_masks — Number of masks in masks.

win — Specifies the window.

XIEventMask *XIGetSelectedEvents( Display *display,
                                  Window win,
                                  int *num_masks_return);

display</purl> — Specifies the connection to the X server.

num_masks_return — Number of masks in the return value.

win — Specifies the window.

ngl the two functions share three arg names and it's giving twin energy 👯 but they are NOT the same function, don't mix them up.

---

🦋 DESCRIPTION 🦋

okay so, the ✨lore✨:

XI2 events must be selected using XISelectEvents. that's not optional, that's the whole entrance exam. 🔥

XISelectEvents sets the event mask for this client on win. Further events are only reported to this client if the event type matches the selected event mask. The masks overrides the previously selected event mask for the given device. (yes — overrides, like when your old hyperfixation gets replaced by a new one. gone. replaced. no notes.)

If deviceid is a valid device, the event mask is selected only for this device. If deviceid is XIAllDevices or XIAllMasterDevices, the event mask is selected for all devices or all master devices, respectively. The effective event mask is the bit-wise OR of the XIAllDevices, XIAllMasterDevices and the respective device's event mask.

and now, the moment you've been waiting for, the struct reveal 👑:

typedef struct {
    int deviceid;
    int mask_len;
    unsigned char* mask;
} XIEventMask;

The mask_len specifies the length of mask in bytes. mask is a binary mask in the form of (1 << event type). deviceid must be either a device or XIAllDevices or XIAllMasterDevices. A client may submit several masks with the same deviceid in one request but only the last mask will be effective.

🚨 bestie listen: only the last mask will be effective if you send several with the same deviceid. the earlier ones are getting ghosted. if that's not what you want, don't do it. periodt.

XISelectEvents can generate a BadValue, a BadDevice, and a BadWindow error.

---

💜 XIGetSelectedEvents — the reading era 💜

XIGetSelectedEvents returns the events selected by this client on the given window. If no events were selected on this window, XIGetSelectedEvents returns NULL and num_masks_return is set to 0. If an internal error occurs, XIGetSelectedEvents returns NULL and num_masks_return is set to -1. Otherwise, XIGetSelectedEvent returns the selected event masks for all devices including the masks for XIAllDevices and XIAllMasterDevices

⚠️ okay so NULL + 0 and NULL + -1 are two completely different moods. one is "nothing selected, all chill 🌈", the other is "internal error, something is wrong 😭". check num_masks_return, always, fr fr.

The caller must free the returned data using XFree().

💀 not me reminding you again: free it with XFree(). the returned data is yours to clean up, it's not going to tidy itself. main character energy includes memory hygiene, iykyk.

---

🎀 DIAGNOSTICS 🎀

• BadValue — A value is outside of the permitted range.
• BadWindow — A value for a Window argument does not name a defined window.
• BadDevice — An invalid device was specified. The device does not exist.

---

and that's the whole page, bestie — every option, every field, every error, nothing skipped, nothing invented. ate and left no crumbs. 💅✨

this was XISELECTEVENTS(3) from the XISELECTEVENTS(3) manual, dated 05/18/2026 — shoutout to the source and version for keeping it iconic. mwah. 🎀🦋