XGETDEVICEPROPERTY(3)

💖 XGETDEVICEPROPERTY(3) 💖

okay bestie, sit down, hydrate, because today we're learning about device properties in XInput — the XGetDeviceProperty, XChangeDeviceProperty and XDeleteDeviceProperty trio. this is from the XGETDEVICEPROPERTY(3) manual page, and yes we are reading all of it. no skimming. periodt. ✨

---

🌸 NAME 🌸

XGetDeviceProperty, XChangeDeviceProperty, XDeleteDeviceProperty — get, change, or delete a device's property. that's it, that's the whole vibe: read it, write it, yeet it 💅

---

✨ SYNOPSIS ✨

first, you gotta pull in the header, like so:

#include <X11/extensions/XInput.h>

then here's the three besties in all their glory:

int XGetDeviceProperty( Display *display,
                        XDevice *device,
                        Atom property,
                        long offset,
                        long length,
                        Bool delete,
                        Atom req_type,
                        Atom *actual_type_return,
                        int *actual_format_return,
                        unsigned long *nitems_return,
                        unsigned long *bytes_after_return,
                        unsigned char **prop_return)

void XChangeDeviceProperty( Display *display,
                            XDevice *device,
                            Atom property,
                            Atom type,
                            int format,
                            int mode,
                            const unsigned char *data,
                            int nelements)

void XDeleteDeviceProperty( Display *display,
                            XDevice *device,
                            Atom property)

---

🎀 the arguments, explained with love 🎀

• actual_type_return — hands you back an atom identifier that defines the actual type of the property. it's giving "surprise, here's what it really is" 👑
• actual_format_return — returns the actual format of the property. not the format you asked for, the format you got. character development fr fr.
• bytes_after_return — returns how many bytes are still left to read in the property, but only if a partial read happened. the leftovers, basically 🍓
• data — specifies the property data. the actual goods.
• delete — specifies a Boolean value that determines whether the property is deleted. yes, this one is literally called delete. iconic naming, no notes.
• display — specifies the connection to the X server. your link to the mothership 🔥
• device — the device to grab. (yes, even though we're not grabbing, the manpage says grab. we respect the manpage.)
• format — specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. possible values are 8, 16, and 32. this info is what lets the X server correctly do byte-swap operations when it needs to. ⚠️ and heads up: if the format is 16-bit or 32-bit, you must explicitly cast the data pointer to an (unsigned char*) in the call to XChangeDeviceProperty. no skipping that cast, bestie, that's a "trust me" moment 😭
• length — specifies the length, in 32-bit multiplies, of the data to be retrieved.
• mode — specifies the mode of operation. you can pass PropModeReplace, PropModePrepend, or PropModeAppend. replace, prepend, or append — pick your fighter ✨
• nelements — specifies the number of elements in data.
• nitems_return — returns the actual number of 8-bit, 16-bit, or 32-bit items stored in the prop_return array.
• num_values — specifies the number of elements in the values list. (she's here. she's in the list. we include her. 💜)
• offset — specifies the offset in the specified property (in 32-bit quantities) where the data is to be retrieved. like a little bookmark in the middle of the property 🔖
• property — specifies the property to modify or query.
• prop_return — returns the data in the specified format. here's the breakdown so you don't get jumpscared:
  • if the returned format is 8, the returned data is represented as a char array.
  • if the returned format is 16, the returned data is represented as an array of short int type and should be cast to that type to obtain the elements.
  • if the returned format is 32, the property data will be stored as an array of longs — which, in a 64-bit application, will be 64-bit values that are padded in the upper 4 bytes. yes really. we don't make the rules 🙈
• req_type — specifies the atom identifier associated with the property type, or AnyPropertyType. "any" as in, you're not picky, you'll take what you get 💅

---

🦋 DESCRIPTION 🦋

so, XGetDeviceProperty — she returns the actual type of the property, the actual format of the property, the number of 8-bit, 16-bit, or 32-bit items transferred, the number of bytes remaining to be read in the property, and a pointer to the data actually returned. five things, one call. multitasking queen. for a detailed description of this function, see the man page to XGetWindowProperty.

then XChangeDeviceProperty — she alters the property for the specified device, and causes the server to generate a XPropertyNotifyEvent event on that device. 📣 she's loud, she's noticed, she makes the server send an event. for a detailed description of this function, see the man page to XChangeProperty.

and XDeleteDeviceProperty — she deletes the specified device property. 🗑️ but listen: a client cannot delete a property created by a driver or the server. attempting to do so will result in a BadAtom error. so if you try to delete someone else's property, you get a BadAtom in your face. don't do it. it's not your property to delete, bestie 💀

now the error tea, per function:

• XGetDeviceProperty can generate a BadAtom, BadDevice error.
• XChangeDeviceProperty can generate a BadDevice, a BadMatch, a BadAtom, and a BadValue error.
• XDeleteDeviceProperty can generate a BadDevice, and a BadAtom error.

---

💅 DIAGNOSIS 💅

these are the errors and what they actually mean:

• BadAtom — a value does not describe a valid named identifier, or the client attempted to remove a driver-allocated property. (yeah. that second one. that's the one we warned you about. 🫠)
• BadDevice — an invalid device was specified. the device does not exist. she's not there. she was never there. 😭

---

🌈 SEE ALSO 🌈

• XListDeviceProperties(3)

go read that one next, it's the natural sequel ✨

---

and that's the whole page, bestie!! this was XGETDEVICEPROPERTY(3), dated 05/18/2026, and the manual page itself lives under the name XGETDEVICEPROPERTY(3). mwah. 💖 go forth and query your devices responsibly. 🎀🦋🌸