xcb_get_property(3)

💖 xcb_get_property(3) — the XCB Requests glow-up 💖

okay bestie, sit down, hydrate, because today we're learning how to get a window property and honestly? it's giving main character energy. this is xcb_get_property, straight from the XCB Requests lineup, and by the end of this page you're gonna be reading other windows' properties like it's their diary. 🦋

---

✨ NAME ✨

xcb_get_property — Gets a window property 💅

---

🌸 SYNOPSIS 🌸

first things first, you gotta bring in the header:

#include <xcb/xproto.h>

🎀 Request function

xcb_get_property_cookie_t xcb_get_property(xcb_connection_t *conn,
       uint8_t _delete, xcb_window_t window, xcb_atom_t property,
       xcb_atom_t type, uint32_t long_offset, uint32_t long_length);

🎀 Reply datastructure

typedef struct xcb_get_property_reply_t {
    uint8_t    response_type;
    uint8_t    format;
    uint16_t   sequence;
    uint32_t   length;
    xcb_atom_t type;
    uint32_t   bytes_after;
    uint32_t   value_len;
    uint8_t    pad0[12];
} xcb_get_property_reply_t;

🎀 Reply function

xcb_get_property_reply_t *xcb_get_property_reply(xcb_connection_t *conn,
       xcb_get_property_cookie_t cookie, xcb_generic_error_t **e);

🎀 Reply accessors

void *xcb_get_property_value(const xcb_get_property_request_t *reply);

int xcb_get_property_value_length(const xcb_get_property_reply_t
       *reply);

xcb_generic_iterator_t xcb_get_property_value_end(const
       xcb_get_property_reply_t *reply);

---

⭐ REQUEST ARGUMENTS ⭐

like, every single one, no skipping, periodt:

• conn — your XCB connection to X11. the whole vibe starts here.
• _delete — whether the property should actually get deleted. and heads up bestie: if you're deleting a property, the type you specify has to match the actual property type. no catfishing allowed. 🙈
• window — the window whose property you're trying to get. yes, that window.
• property — the property you want to get (it's an atom).
• type — the type of the property you want to get (also an atom).
• long_offset — the offset (in 32-bit multiples!) in the specified property where the data should start being retrieved from.
• long_length — how many 32-bit multiples of data should be retrieved. so if you set long_length to 4, you'll receive 16 bytes of data. math! we love her. ✨

---

💜 REPLY FIELDS 💜

• response_type — the type of this reply, which in this case is XCB_GET_PROPERTY. this field is also chillin' in the xcb_generic_reply_t, and you can use it to tell replies apart from each other.
• sequence — the sequence number of the last request processed by the X11 server.
• length — the length of the reply, in words (and a word is 4 bytes, ikr).
• format — tells you 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 lets the X server correctly do byte-swap operations when it needs to. so thoughtful of it.
• type — the actual type of the property (an atom).
• bytes_after — how many bytes are remaining to be read in the property if a partial read happened.
• value_len — the length of value. and bestie, please use the corresponding accessor instead of this field. i'm literally begging. 🫶

---

🦋 DESCRIPTION 🦋

so what does it do? it gets the specified property from the specified window. properties are things like the window title (WM_NAME) or its minimum size (WM_NORMAL_HINTS). protocols like EWMH also use properties — for example, EWMH defines the window title, encoded as a UTF-8 string, in the _NET_WM_NAME property.

and then, iconic honesty from the original authors:

• TODO: talk about type
• TODO: talk about delete
• TODO: talk about the offset/length thing. what's a valid use case?

we respect the transparency. 💀

---

🔥 RETURN VALUE 🔥

it returns an xcb_get_property_cookie_t. errors have to be handled when you call the reply function xcb_get_property_reply.

but if you'd rather handle errors in the event loop instead, use xcb_get_property_unchecked. see xcb-requests(3) for the deets.

---

👑 ERRORS 👑

• xcb_atom_error_t — property or type do not refer to a valid atom. fake atoms get denied, sorry.
• xcb_value_error_t — the specified long_offset is beyond the actual property length (e.g. the property has a length of 3 bytes and you are setting long_offset to 1, resulting in a byte offset of 4). yeah, that's out of bounds, bestie.
• xcb_window_error_t — the specified window does not exist. it's not there. it never was. 😭

---

🌈 EXAMPLE 🌈

here's the whole thing, verbatim, no notes:

/*
 * Prints the WM_NAME property of the window.
 *
 */
void my_example(xcb_connection_t *c, xcb_window_t window) {
    xcb_get_property_cookie_t cookie;
    xcb_get_property_reply_t *reply;

    /* These atoms are predefined in the X11 protocol. */
    xcb_atom_t property = XCB_ATOM_WM_NAME;
    xcb_atom_t type = XCB_ATOM_STRING;

    // TODO: a reasonable long_length for WM_NAME?
    cookie = xcb_get_property(c, 0, window, property, type, 0, 0);
    if ((reply = xcb_get_property_reply(c, cookie, NULL))) {
        int len = xcb_get_property_value_length(reply);
        if (len == 0) {
            printf("TODO\n");
            free(reply);
            return;
        }
        printf("WM_NAME is %.*s\n", len,
               (char*)xcb_get_property_value(reply));
    }
    free(reply);
}

and yes, don't forget the free(reply) at the end. memory leaks are not the vibe. 🙈

---

🧚 SEE ALSO 🧚

xcb-requests(3), xcb-examples(3), xcb_intern_atom(3), xprop(1)

go read them, iykyk. ✨

---

💖 AUTHOR 💖

Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.

---

okay that's the whole page bestie, you ate that fr fr. this was libxcb 1.17.0, X Version 11, and you just read the xcb_get_property(3) manual page — slay, go get those properties. 💅🌸💜