xcb-examples(3)

✨ xcb-examples ✨

okay bestie, welcome to xcb-examples 💖 this is the lil meta-manpage that explains the vibe behind all the example code scattered through the XCB manpages. no cap.

---

🎀 NAME 🎀

xcb-examples — manpage examples. yes, the manpage is literally about the examples inside other manpages. it's giving inception, it's giving meta, we love her 💅

---

🌸 DESCRIPTION 🌸

so many of the XCB manpages come with example code sprinkled in them 🫶 and the whole point of those examples is to show you how to use one particular part of XCB. one. singular. very specific thing.

here's the tea though: they almost never represent a standalone program, and honestly they're usually not even a useful program on their own 😭 because X11 programs are relatively involved, and that's just... beyond the scope of a manpage example. it's not a skill issue, it's a scope issue. periodt.

---

🦋 ENVIRONMENT 🦋

every single example just assumes you already have an xcb_connection at hand, plus possibly some other variables too. like, if the example is showing you how xcb_get_property works, then bestie you're gonna need the window you want to get the property of. obviously. 🙈

and to make it crystal clear that these variables are your responsibility, not the example's, the examples are written as a single function that takes all the necessary variables as parameters. no sneaky globals, no hidden magic, just parameters. slay.

---

💜 FLUSHING 💜

okay so "flushing" means calling xcb_flush to clear the XCB-internal write buffer and send all pending requests off to the X11 server. it's like hitting send on the group chat, but for requests. ✨

here's the important part, no cap:

• you don't explicitly need to flush before using a reply function (like xcb_query_pointer_reply)
• but you do need to flush before entering the event loop of your program

lowkey this trips everyone up, so let's be super clear about it.

there are only two cases when XCB flushes by itself:

1. when its write buffer becomes full 💀
2. when you're asking for the reply of a request which wasn't flushed out yet (like xcb_query_pointer_reply)

and that second one? it also includes xcb_request_check(). 👑

🚨 please note: waiting for an event does NOT flush. like, at all. not even a little bit.

examples generally include the xcb_flush call where it's appropriate (for example, after setting a property). so if you include these functions and call them in your application, it should just work. 🫶

however — and this is the highkey important nuance — you might get better results when flushing outside of the function, depending on the architecture of your program. so like, context matters, bestie.

---

🌈 COMPILATION 🌈

if an example does not compile (without warnings) when using -std=c99, that is considered a documentation bug. full stop. 🙅

similarly, not handling errors or leaking memory is also considered a documentation bug. yes, even in a tiny example. we hold ourselves to a standard here, it's called ✨excellence✨.

so if you spot any of that, please inform us about it at xcb@lists.freedesktop.org 💌 we genuinely wanna know, fr fr.

---

👑 CODING STYLE 👑

the rules, short and sweet:

• every example uses 4 spaces for indentation
• comments are in asterisks, like /* this */
• no line is longer than 80 characters (including indentation)

that's it, that's the whole style guide. minimal, iconic, consistent. 🎀

---

🔥 SEE ALSO 🔥

• xcb_connect(3)
• xcb_get_property(3)
• xcb_flush(3)

---

🫶 AUTHOR 🫶

Michael Stapelberg <michael+xcb at stapelberg dot de> — thank you for your service, king 👑

---

and that's the whole page bestie!! brought to you by X Version 11 and libxcb 1.17.0 🌟 mwah, go forth and write examples that compile clean and don't leak memory 💖✨