xcb_intern_atom(3)

💫 xcb_intern_atom — get an atom identifier by name 💫

okay bestie, sit down, we're learning about atoms today 💅 this is from the XCB Requests corner of the manual, and it's genuinely so useful, i promise.

---

✨ SYNOPSIS ✨

first things first, you gotta pull in the header:

#include <xcb/xproto.h>

🎀 Request function

xcb_intern_atom_cookie_t xcb_intern_atom(xcb_connection_t *conn,
       uint8_t only_if_exists, uint16_t name_len, const char *name);

🎀 Reply datastructure

typedef struct xcb_intern_atom_reply_t {
    uint8_t    response_type;
    uint8_t    pad0;
    uint16_t   sequence;
    uint32_t   length;
    xcb_atom_t atom;
} xcb_intern_atom_reply_t;

🎀 Reply function

xcb_intern_atom_reply_t *xcb_intern_atom_reply(xcb_connection_t *conn,
       xcb_intern_atom_cookie_t cookie, xcb_generic_error_t **e);

---

🌸 REQUEST ARGUMENTS 🌸

• conn — the XCB connection to X11, your lil hotline to the server, periodt.
• only_if_exists — when this is set, you only get back a valid atom id if the atom already exists. no new atoms, no surprises.
• name_len — the length of the name that comes right after it. yes, you gotta count it yourself, iykyk.
• name — the actual name of the atom. the whole point of the operation bestie 💖

---

🦋 REPLY FIELDS 🦋

• response_type — the type of this reply, which in this case is XCB_INTERN_ATOM. this field also lives in the xcb_generic_reply_t, so you can use it to tell your replies apart from each other. so handy ✨
• sequence — the sequence number of the last request processed by the X11 server. receipts, basically.
• length — the length of the reply, in words (and a word here is 4 bytes, no cap).
• atom — TODO: NOT YET DOCUMENTED. yeah. the docs said what they said 🙈 iconic of them honestly.

---

👑 DESCRIPTION 👑

So what does it actually do? It retrieves the identifier (xcb_atom_t TODO) for the atom with the specified name. Atoms are used in protocols like EWMH, for example to store window titles (the _NET_WM_NAME atom) as a property of a window. the way that works is genuinely so cool 🫶

Here's the vibe on only_if_exists:

• If only_if_exists is 0, the atom will be created if it does not already exist.
• If only_if_exists is 1, XCB_ATOM_NONE will be returned if the atom does not yet exist.

---

⭐ RETURN VALUE ⭐

Returns an xcb_intern_atom_cookie_t. Errors have to be handled when calling the reply function xcb_intern_atom_reply. don't skip that part bestie, that's the whole plot 😭

If you'd rather handle errors in the event loop instead, use xcb_intern_atom_unchecked. See xcb-requests(3) for details. pick your fighter 💅

---

💀 ERRORS 💀

• xcb_alloc_error_t — TODO: reasons? that's literally what it says. mystery error, main character energy ✨
• xcb_value_error_t — a value other than 0 or 1 was specified for only_if_exists. so like, don't do that. binary means binary 🚫

---

🌈 EXAMPLE 🌈

here's the whole thing in action, resolving the _NET_WM_NAME atom:

/*
 * Resolves the _NET_WM_NAME atom.
 *
 */
void my_example(xcb_connection_t *c) {
    xcb_intern_atom_cookie_t cookie;
    xcb_intern_atom_reply_t *reply;

    cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
    /* ... do other work here if possible ... */
    if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
        printf("The _NET_WM_NAME atom has ID %u0, reply->atom);
        free(reply);
    }
}

notice how you fire off the request, go do other stuff while the server thinks, and only then come back for the reply? that's the async slay, we love to see it 🔥

---

🍓 SEE ALSO 🍓

xcb-requests(3), xcb-examples(3), xcb_get_atom_name(3), xlsatoms(1)

---

🧚 AUTHOR 🧚

Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements. they're literally asking for feedback, so if you spot something, tell them 🫶

---

okay that's the whole page, you ate it, no crumbs left 💅

this lil gem comes to you from X Version 11, libxcb 1.17.0. now go intern some atoms bestie, you're gonna do amazing 🌸✨🦋