---
name: "wl_message"
section: "3"
platform: "linux"
package: "wayland-docs"
version: "1.26.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/wl_message"
---

# wl\_message(3)

## NAME

wl\_message

## SYNOPSIS

\#include \<wayland-util.h\>

### Data Fields

const char \* **name**\
 const char \* **signature**\
 const struct **wl\_interface** \*\* **types**\

## Detailed Description

Protocol message signature

A **wl\_message** describes the signature of an actual protocol message, such as a request or event, that adheres to the Wayland protocol wire format. The protocol implementation uses a **wl\_message** within its demarshal machinery for decoding messages between a compositor and its clients. In a sense, a **wl\_message** is to a protocol message like a class is to an object.

The **name of a wl\_message is the name of the corresponding protocol message.**

**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. 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.**

**When no arguments accompany a message, signature is an empty string.**

**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.**

**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.**

**See also**

**wl\_argument**

**wl\_interface**

Wire Format

## Field Documentation

### const char\* wl\_message::name

**Message name**

### const char\* wl\_message::signature

**Message signature**

### const struct wl\_interface\*\* wl\_message::types

**Object argument interfaces**

## Author

**Generated automatically by Doxygen for Wayland from the source code.**