wl_message(3)

🎀 NAME 🎀

wl_message — the little struct that spills the tea on what a protocol message actually looks like, bestie 💅 (this page lives in the Library Functions Manual, section 3, so yes she's a library function situation)

---

🌸 SYNOPSIS 🌸

#include <wayland-util.h>

✨ Data Fields ✨

• const char * name
• const char * signature
• const struct wl_interface ** types

---

💖 Detailed Description 💖

Protocol message signature 🦋

Okay so picture this: a wl_message describes the signature of an actual protocol message — like a request or an event — and it has to play by the rules of the Wayland protocol wire format. The protocol implementation uses a wl_message inside its demarshal machinery to decode messages going back and forth between a compositor and its clients. In a sense, a wl_message is to a protocol message like a class is to an object. periodt. 👑

The name of a wl_message is the name of the corresponding protocol message. iconic, no notes.

The signature is an ordered list of symbols representing the data types of message arguments and, optionally, a protocol version and indicators for nullability. A leading integer in the signature indicates the since version of the protocol message. A ? preceding a data type symbol indicates that the following argument type is nullable.

🚨 Okay serious moment, bestie: while it is a protocol violation to send messages with non-nullable arguments set to NULL, event handlers in clients might still get called with non-nullable object arguments set to NULL. This can happen when the client destroyed the object being used as argument on its side and an event referencing that object was sent before the server knew about its destruction. As this race cannot be prevented, clients should — as a general rule — program their event handlers such that they can handle object arguments declared non-nullable being NULL gracefully. 😭 not the race condition.

When no arguments accompany a message, signature is an empty string. (yes, literally empty, it's giving minimalism 💀)

🔤 Symbols 🔤

• i: int
• u: uint
• f: fixed
• s: string
• o: object
• n: new_id
• a: array
• h: fd
• ?: following argument (o or s) is nullable

---

While demarshaling primitive arguments is straightforward, when demarshaling messages containing object or new_id arguments, the protocol implementation often must determine the type of the object. The types of a wl_message is an array of wl_interface references that correspond to o and n arguments in signature, with NULL placeholders for arguments with non-object types. 🫶

Consider the protocol event wl_display delete_id that has a single uint argument. The wl_message is:

{ "delete_id", "u", [NULL] }

Here, the message name is "delete_id", the signature is "u", and the argument types is [NULL], indicating that the uint argument has no corresponding wl_interface since it is a primitive argument. simple. clean. slay. ✨

In contrast, consider a wl_foo interface supporting protocol request bar that has existed since version 2, and has two arguments: a uint and an object of type wl_baz_interface that may be NULL. Such a wl_message might be:

{ "bar", "2u?o", [NULL, &wl_baz_interface] }

Here, the message name is "bar", and the signature is "2u?o". Notice how the 2 indicates the protocol version, the u indicates the first argument type is uint, and the ?o indicates that the second argument is an object that may be NULL. Lastly, the argument types array indicates that no wl_interface corresponds to the first argument, while the type wl_baz_interface corresponds to the second argument. ate that explanation up fr fr 💅

👀 See also 👀

• wl_argument
• wl_interface
• Wire Format

---

📚 Field Documentation 📚

🌈 const char* wl_message::name 🌈

Message name — the whole identity, the name tag, the "hi my name is" sticker 🎀

🌈 const char* wl_message::signature 🌈

Message signature — the symbol soup that says what the args are 🧚

🌈 const struct wl_interface** wl_message::types 🌈

Object argument interfaces — the lookup table for your o and n girls 💖

---

✍️ Author ✍️

Generated automatically by Doxygen for Wayland from the source code. (not a human author, just the robot doing its little thing 🤖✨)

---

and that's the whole page, bestie! this one came from Wayland, Version 1.26.0, and it's the wl_message(3) page — so next time you see a signature string like "2u?o" just know you're fluent now 💜🦋 periodt.