---
name: "wl_display"
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_display"
---

# wl\_display(3)

Represents a connection to the compositor and acts as a proxy to the wl\_display singleton object.

## NAME

wl\_display - Represents a connection to the compositor and acts as a proxy to the **wl\_display** singleton object.

## SYNOPSIS

\#include \<wayland-client-core.h\>

### Public Member Functions

struct **wl\_client** \* **wl\_client\_create** (struct **wl\_display** \*display, int fd)\
 struct **wl\_display** \* **wl\_display\_create** (void)\
 void **wl\_display\_destroy** (struct **wl\_display** \*display)\
 void **wl\_display\_set\_global\_filter** (struct **wl\_display** \*display, **wl\_display\_global\_filter\_func\_t** filter, void \*data)\
 uint32\_t **wl\_display\_get\_serial** (const struct **wl\_display** \*display)\
 uint32\_t **wl\_display\_next\_serial** (struct **wl\_display** \*display)\
 void **wl\_display\_destroy\_clients** (struct **wl\_display** \*display)\
 void **wl\_display\_set\_default\_max\_buffer\_size** (struct **wl\_display** \*display, size\_t **max\_buffer\_size**)\
 const char \* **wl\_display\_add\_socket\_auto** (struct **wl\_display** \*display)\
 int **wl\_display\_add\_socket\_fd** (struct **wl\_display** \*display, int sock\_fd)\
 int **wl\_display\_remove\_socket\_fd** (struct **wl\_display** \*display, int sock\_fd)\
 int **wl\_display\_add\_socket** (struct **wl\_display** \*display, const char \*name)\
 struct **wl\_protocol\_logger** \* **wl\_display\_add\_protocol\_logger** (struct **wl\_display** \*display, **wl\_protocol\_logger\_func\_t** func, void \*user\_data)\
 uint32\_t \* **wl\_display\_add\_shm\_format** (struct **wl\_display** \*display, uint32\_t format)\
 struct **wl\_list** \* **wl\_display\_get\_client\_list** (struct **wl\_display** \*display)\
 struct **wl\_event\_queue** \* **wl\_display\_create\_queue** (struct **wl\_display** \*display)\
 struct **wl\_event\_queue** \* **wl\_display\_create\_queue\_with\_name** (struct **wl\_display** \*display, const char \*name)\
 struct **wl\_display** \* **wl\_display\_connect\_to\_fd** (int fd)\
 struct **wl\_display** \* **wl\_display\_connect** (const char \*name)\
 void **wl\_display\_disconnect** (struct **wl\_display** \*display)\
 int **wl\_display\_get\_fd** (struct **wl\_display** \*display)\
 int **wl\_display\_roundtrip\_queue** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue)\
 int **wl\_display\_roundtrip** (struct **wl\_display** \*display)\
 int **wl\_display\_read\_events** (struct **wl\_display** \*display)\
 int **wl\_display\_prepare\_read\_queue** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue)\
 int **wl\_display\_prepare\_read** (struct **wl\_display** \*display)\
 void **wl\_display\_cancel\_read** (struct **wl\_display** \*display)\
 int **wl\_display\_dispatch\_queue\_timeout** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue, const struct timespec \*timeout)\
 int **wl\_display\_dispatch\_queue** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue)\
 int **wl\_display\_dispatch\_queue\_pending** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue)\
 int **wl\_display\_dispatch\_queue\_pending\_single** (struct **wl\_display** \*display, struct **wl\_event\_queue** \*queue)\
 int **wl\_display\_dispatch** (struct **wl\_display** \*display)\
 int **wl\_display\_dispatch\_pending** (struct **wl\_display** \*display)\
 int **wl\_display\_dispatch\_pending\_single** (struct **wl\_display** \*display)\
 int **wl\_display\_get\_error** (struct **wl\_display** \*display)\
 uint32\_t **wl\_display\_get\_protocol\_error** (struct **wl\_display** \*display, const struct **wl\_interface** \*\*interface, uint32\_t \*id)\
 int **wl\_display\_flush** (struct **wl\_display** \*display)\
 void **wl\_display\_set\_max\_buffer\_size** (struct **wl\_display** \*display, size\_t **max\_buffer\_size**)\

### Data Fields

struct **wl\_event\_loop** \* **loop**\
 bool **run**\
 uint32\_t **next\_global\_name**\
 uint32\_t **serial**\
 struct **wl\_list** **registry\_resource\_list**\
 struct **wl\_list** **global\_list**\
 struct **wl\_list** **socket\_list**\
 struct **wl\_list** **client\_list**\
 struct **wl\_list** **protocol\_loggers**\
 struct wl\_priv\_signal **destroy\_signal**\
 struct wl\_priv\_signal **create\_client\_signal**\
 struct **wl\_array** **additional\_shm\_formats**\
 **wl\_display\_global\_filter\_func\_t** **global\_filter**\
 void \* **global\_filter\_data**\
 int **terminate\_efd**\
 struct **wl\_event\_source** \* **term\_source**\
 size\_t **max\_buffer\_size**\

## Detailed Description

Represents a connection to the compositor and acts as a proxy to the **wl\_display** singleton object.

A **wl\_display** object represents a client connection to a Wayland compositor. It is created with either **wl\_display\_connect()** or **wl\_display\_connect\_to\_fd()**. A connection is terminated using **wl\_display\_disconnect()**.

A **wl\_display** is also used as the **wl\_proxy** for the **wl\_display** singleton object on the compositor side.

A **wl\_display** object handles all the data sent from and to the compositor. When a **wl\_proxy** marshals a request, it will write its wire representation to the display's write buffer. The data is sent to the compositor when the client calls **wl\_display\_flush()**.

Incoming data is handled in two steps: queueing and dispatching. In the queue step, the data coming from the display fd is interpreted and added to a queue. On the dispatch step, the handler for the incoming event set by the client on the corresponding **wl\_proxy** is called.

A **wl\_display** has at least one event queue, called the *default queue*. Clients can create additional event queues with **wl\_display\_create\_queue()** and assign **wl\_proxy**'s to it. Events occurring in a particular proxy are always queued in its assigned queue. A client can ensure that a certain assumption, such as holding a lock or running from a given thread, is true when a proxy event handler is called by assigning that proxy to an event queue and making sure that this queue is only dispatched when the assumption holds.

The default queue is dispatched by calling **wl\_display\_dispatch()**. This will dispatch any events queued on the default queue and attempt to read from the display fd if it's empty. Events read are then queued on the appropriate queues according to the proxy assignment.

A user created queue is dispatched with **wl\_display\_dispatch\_queue()**. This function behaves exactly the same as **wl\_display\_dispatch()** but it dispatches given queue instead of the default queue.

A real world example of event queue usage is Mesa's implementation of eglSwapBuffers() for the Wayland platform. This function might need to block until a frame callback is received, but dispatching the default queue could cause an event handler on the client to start drawing again. This problem is solved using another event queue, so that only the events handled by the EGL code are dispatched during the block.

This creates a problem where a thread dispatches a non-default queue, reading all the data from the display fd. If the application would call *[poll(2)](/poll/2.md)* after that it would block, even though there might be events queued on the default queue. Those events should be dispatched with **wl\_display\_dispatch\_pending()** or **wl\_display\_dispatch\_queue\_pending()** before flushing and blocking.

## Member Function Documentation

### struct wl\_client \* wl\_client\_create (struct wl\_display \* display, int fd)

Create a client for the given file descriptor

**Parameters**

*display* The display object \
 *fd* The file descriptor for the socket to the client

**Returns**

The new client object or NULL on failure.

Given a file descriptor corresponding to one end of a socket, this function will create a **wl\_client** struct and add the new client to the compositors client list. At that point, the client is initialized and ready to run, as if the client had connected to the servers listening socket. When the client eventually sends requests to the compositor, the **wl\_client** argument to the request handler will be the **wl\_client** returned from this function.

The other end of the socket can be passed to **wl\_display\_connect\_to\_fd()** on the client side or used with the WAYLAND\_SOCKET environment variable on the client side.

Listeners added with **wl\_display\_add\_client\_created\_listener()** will be notified by this function after the client is fully constructed.

On failure this function sets errno accordingly and returns NULL.

On success, the new client object takes the ownership of the file descriptor. On failure, the ownership of the socket endpoint file descriptor is unchanged, it is the responsibility of the caller to perform cleanup, e.g. call close().

### struct wl\_protocol\_logger \* wl\_display\_add\_protocol\_logger (struct wl\_display \* display, wl\_protocol\_logger\_func\_t func, void \* user\_data)

Adds a new protocol logger.

When a new protocol message arrives or is sent from the server all the protocol logger functions will be called, carrying the *user\_data* pointer, the type of the message (request or event) and the actual message. The lifetime of the messages passed to the logger function ends when they return so the messages cannot be stored and accessed later.

*errno* is set on error.

**Parameters**

*display* The display object \
 *func* The function to call to log a new protocol message \
 *user\_data* The user data pointer to pass to *func*

**Returns**

The protocol logger object on success, NULL on failure.

**See also**

**wl\_protocol\_logger\_destroy**

### uint32\_t \* wl\_display\_add\_shm\_format (struct wl\_display \* display, uint32\_t format)

Add support for a wl\_shm pixel format

**Parameters**

*display* The display object \
 *format* The wl\_shm pixel format to advertise

**Returns**

A pointer to the wl\_shm format that was added to the list or NULL if adding it to the list failed.

Add the specified wl\_shm format to the list of formats the wl\_shm object advertises when a client binds to it. Adding a format to the list means that clients will know that the compositor supports this format and may use it for creating wl\_shm buffers. The compositor must be able to handle the pixel format when a client requests it.

The compositor by default supports WL\_SHM\_FORMAT\_ARGB8888 and WL\_SHM\_FORMAT\_XRGB8888.

### int wl\_display\_add\_socket (struct wl\_display \* display, const char \* name)

Add a socket to Wayland display for the clients to connect.

**Parameters**

*display* Wayland display to which the socket should be added. \
 *name* Name of the Unix socket.

**Returns**

0 if success. -1 if failed.

This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display.

If NULL is passed as name, then it would look for WAYLAND\_DISPLAY env variable for the socket name. If WAYLAND\_DISPLAY is not set, then default wayland-0 is used.

If the socket name is a relative path, the Unix socket will be created in the directory pointed to by environment variable XDG\_RUNTIME\_DIR. If XDG\_RUNTIME\_DIR is invalid or not set, then this function fails and returns -1.

If the socket name is an absolute path, then it is used as-is for the the Unix socket.

The length of the computed socket path must not exceed the maximum length of a Unix socket path. The function also fails if the user does not have write permission in the directory or if the path is already in use.

### const char \* wl\_display\_add\_socket\_auto (struct wl\_display \* display)

Automatically pick a Wayland display socket for the clients to connect to.

**Parameters**

*display* Wayland display to which the socket should be added.

**Returns**

The socket name if success. NULL if failed.

This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display. The name of the socket is chosen automatically as the first available name in the sequence "wayland-0", "wayland-1", "wayland-2", ..., "wayland-32".

The string returned by this function is owned by the library and should not be freed.

**See also**

**wl\_display\_add\_socket**

### int wl\_display\_add\_socket\_fd (struct wl\_display \* display, int sock\_fd)

Add a socket with an existing fd to Wayland display for the clients to connect.

**Parameters**

*display* Wayland display to which the socket should be added. \
 *sock\_fd* The existing socket file descriptor to be used

**Returns**

0 if success. -1 if failed.

The existing socket fd must already be created, opened, and locked. The fd must be properly set to CLOEXEC and bound to a socket file with both bind() and listen() already called.

On success, the socket fd ownership is transferred to libwayland: libwayland will close the socket when the display is destroyed or when **wl\_display\_remove\_socket\_fd()** is called.

### void wl\_display\_cancel\_read (struct wl\_display \* display)

Cancel read intention on display's fd

**Parameters**

*display* The display context object

After a thread successfully called **wl\_display\_prepare\_read()** it must either call **wl\_display\_read\_events()** or **wl\_display\_cancel\_read()**. If the threads do not follow this rule it will lead to deadlock.

**See also**

**wl\_display\_prepare\_read()**, **wl\_display\_read\_events()**

### struct wl\_display \* wl\_display\_connect (const char \* name)

Connect to a Wayland display

**Parameters**

*name* Name of the Wayland display to connect to

**Returns**

A **wl\_display** object or NULL on failure

Connect to the Wayland display named name. If name is NULL, its value will be replaced with the WAYLAND\_DISPLAY environment variable if it is set, otherwise display "wayland-0" will be used.

If WAYLAND\_SOCKET is set, it's interpreted as a file descriptor number referring to an already opened socket. In this case, the socket is used as-is and name is ignored.

If name is a relative path, then the socket is opened relative to the XDG\_RUNTIME\_DIR directory.

If name is an absolute path, then that path is used as-is for the location of the socket at which the Wayland server is listening; no qualification inside XDG\_RUNTIME\_DIR is attempted.

If name is NULL and the WAYLAND\_DISPLAY environment variable is set to an absolute pathname, then that pathname is used as-is for the socket in the same manner as if name held an absolute path. Support for absolute paths in name and WAYLAND\_DISPLAY is present since Wayland version 1.15.

### struct wl\_display \* wl\_display\_connect\_to\_fd (int fd)

Connect to Wayland display on an already open fd

**Parameters**

*fd* The fd to use for the connection

**Returns**

A **wl\_display** object or NULL on failure

The **wl\_display** takes ownership of the fd and will close it when the display is destroyed. The fd will also be closed in case of failure.

### struct wl\_display \* wl\_display\_create (void )

Create Wayland display object.

**Returns**

The Wayland display object. Null if failed to create

This creates the **wl\_display** object.

### struct wl\_event\_queue \* wl\_display\_create\_queue (struct wl\_display \* display)

Create a new event queue for this display

**Parameters**

*display* The display context object

**Returns**

A new event queue associated with this display or NULL on failure.

### struct wl\_event\_queue \* wl\_display\_create\_queue\_with\_name (struct wl\_display \* display, const char \* name)

Create a new event queue for this display and give it a name

**Parameters**

*display* The display context object \
 *name* A human readable queue name

**Returns**

A new event queue associated with this display or NULL on failure.

### void wl\_display\_destroy (struct wl\_display \* display)

Destroy Wayland display object.

**Parameters**

*display* The Wayland display object which should be destroyed.

This function emits the **wl\_display** destroy signal, releases all the sockets added to this display, free's all the globals associated with this display, free's memory of additional shared memory formats and destroy the display object.

**See also**

**wl\_display\_add\_destroy\_listener**

### void wl\_display\_destroy\_clients (struct wl\_display \* display)

Destroy all clients connected to the display

**Parameters**

*display* The display object

This function should be called right before **wl\_display\_destroy()** to ensure all client resources are closed properly. Destroying a client from within **wl\_display\_destroy\_clients()** is safe, but creating one will leak resources and raise a warning.

### void wl\_display\_disconnect (struct wl\_display \* display)

Close a connection to a Wayland display

**Parameters**

*display* The display context object

Close the connection to display. The **wl\_proxy** and **wl\_event\_queue** objects need to be manually destroyed by the caller before disconnecting.

### int wl\_display\_dispatch (struct wl\_display \* display)

Process incoming events

**Parameters**

*display* The display context object

**Returns**

The number of dispatched events on success or -1 on failure

Dispatch events on the default event queue.

If the default event queue is empty, this function blocks until there are events to be read from the display fd. Events are read and queued on the appropriate event queues. Finally, events on the default event queue are dispatched. On failure -1 is returned and errno set appropriately.

In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is required, see **wl\_display\_prepare\_read\_queue()** of how to do so.

This function is thread safe as long as it dispatches the right queue on the right thread. It is also compatible with the multi thread event reading preparation API (see **wl\_display\_prepare\_read\_queue()**), and uses the equivalent functionality internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

**Note**

It is not possible to check if there are events on the queue or not. For dispatching default queue events without blocking, see **wl\_display\_dispatch\_pending()**.

**See also**

**wl\_display\_dispatch\_pending()**, **wl\_display\_dispatch\_queue()**, **wl\_display\_read\_events()**

### int wl\_display\_dispatch\_pending (struct wl\_display \* display)

Dispatch default queue events without reading from the display fd

**Parameters**

*display* The display context object

**Returns**

The number of dispatched events or -1 on failure

This function dispatches events on the main event queue. It does not attempt to read the display fd and simply returns zero if the main queue is empty, i.e., it doesn't block.

**See also**

**wl\_display\_dispatch()**, **wl\_display\_dispatch\_queue()**, **wl\_display\_flush()**

### int wl\_display\_dispatch\_pending\_single (struct wl\_display \* display)

Dispatch at most one pending event in the default event queue.

**Parameters**

*display* The display context object

**Returns**

The number of dispatched events (0 or 1) on success or -1 on failure

Dispatch at most one pending event for objects assigned to the default event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.

**Since**

1\.25.0

### int wl\_display\_dispatch\_queue (struct wl\_display \* display, struct wl\_event\_queue \* queue)

Dispatch events in an event queue

**Parameters**

*display* The display context object \
 *queue* The event queue to dispatch

**Returns**

The number of dispatched events on success or -1 on failure

Dispatch events on the given event queue.

If the given event queue is empty, this function blocks until there are events to be read from the display fd. Events are read and queued on the appropriate event queues. Finally, events on given event queue are dispatched. On failure -1 is returned and errno set appropriately.

In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is required, see **wl\_display\_prepare\_read\_queue()** of how to do so.

This function is thread safe as long as it dispatches the right queue on the right thread. It is also compatible with the multi thread event reading preparation API (see **wl\_display\_prepare\_read\_queue()**), and uses the equivalent functionality internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

It can be used as a helper function to ease the procedure of reading and dispatching events.

**Note**

Since Wayland 1.5 the display has an extra queue for its own events (i. e. delete\_id). This queue is dispatched always, no matter what queue we passed as an argument to this function. That means that this function can return even when it has not dispatched any event for the given queue.

**See also**

**wl\_display\_dispatch()**, **wl\_display\_dispatch\_pending()**, **wl\_display\_dispatch\_queue\_pending()**, **wl\_display\_prepare\_read\_queue()**

### int wl\_display\_dispatch\_queue\_pending (struct wl\_display \* display, struct wl\_event\_queue \* queue)

Dispatch pending events in an event queue

**Parameters**

*display* The display context object \
 *queue* The event queue to dispatch

**Returns**

The number of dispatched events on success or -1 on failure

Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.

**Since**

1\.0.2

### int wl\_display\_dispatch\_queue\_pending\_single (struct wl\_display \* display, struct wl\_event\_queue \* queue)

Dispatch at most one pending event in an event queue

**Parameters**

*display* The display context object \
 *queue* The event queue to dispatch

**Returns**

The number of dispatched events (0 or 1) on success or -1 on failure

Dispatch at most one pending event for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.

**Since**

1\.25.0

### int wl\_display\_dispatch\_queue\_timeout (struct wl\_display \* display, struct wl\_event\_queue \* queue, const struct timespec \* timeout)

Dispatch events in an event queue with a timeout

**Parameters**

*display* The display context object \
 *queue* The event queue to dispatch \
 *timeout* A timeout describing how long the call should block trying to dispatch events

**Returns**

The number of dispatched events on success, -1 on failure

This function behaves identical to **wl\_display\_dispatch\_queue()** except that it also takes a timeout and returns 0 if the timeout elapsed.

Passing NULL as a timeout means an infinite timeout. An empty timespec causes **wl\_display\_dispatch\_queue\_timeout()** to return immediately even if no events have been dispatched.

If a timeout is passed to **wl\_display\_dispatch\_queue\_timeout()** it is updated to the remaining time.

**See also**

**wl\_display\_dispatch\_queue()**

### int wl\_display\_flush (struct wl\_display \* display)

Send all buffered requests on the display to the server

**Parameters**

*display* The display context object

**Returns**

The number of bytes sent on success or -1 on failure

Send all buffered data on the client side to the server. Clients should always call this function before blocking on input from the display fd. On success, the number of bytes sent to the server is returned. On failure, this function returns -1 and errno is set appropriately.

**wl\_display\_flush()** never blocks. It will write as much data as possible, but if all data could not be written, errno will be set to EAGAIN and -1 returned. In that case, use poll on the display file descriptor to wait for it to become writable again.

### struct wl\_list \* wl\_display\_get\_client\_list (struct wl\_display \* display)

Get the list of currently connected clients

**Parameters**

*display* The display object

This function returns a pointer to the list of clients currently connected to the display. You can iterate on the list by using the *wl\_client\_for\_each* macro. The returned value is valid for the lifetime of the *display*. You must not modify the returned list, but only access it.

**See also**

**wl\_client\_for\_each()**

**wl\_client\_get\_link()**

**wl\_client\_from\_link()**

### int wl\_display\_get\_error (struct wl\_display \* display)

Retrieve the last error that occurred on a display

**Parameters**

*display* The display context object

**Returns**

The last error that occurred on display or 0 if no error occurred

Return the last error that occurred on the display. This may be an error sent by the server or caused by the local client.

**Note**

Errors are **fatal**. If this function returns non-zero the display can no longer be used.

### int wl\_display\_get\_fd (struct wl\_display \* display)

Get a display context's file descriptor

**Parameters**

*display* The display context object

**Returns**

Display object file descriptor

Return the file descriptor associated with a display so it can be integrated into the client's main loop.

### uint32\_t wl\_display\_get\_protocol\_error (struct wl\_display \* display, const struct wl\_interface \*\* interface, uint32\_t \* id)

Retrieves the information about a protocol error:

**Parameters**

*display* The Wayland display \
 *interface* if not NULL, stores the interface where the error occurred, or NULL, if unknown. \
 *id* if not NULL, stores the object id that generated the error, or 0, if the object id is unknown. There's no guarantee the object is still valid; the client must know if it deleted the object.

**Returns**

The error code as defined in the interface specification.

```
int err = wl_display_get_error(display);
if (err == EPROTO) {
       code = wl_display_get_protocol_error(display, &interface, &id);
       handle_error(code, interface, id);
}
...
```

### uint32\_t wl\_display\_get\_serial (const struct wl\_display \* display)

Get the current serial number

**Parameters**

*display* The display object

This function returns the most recent serial number, but does not increment it.

### uint32\_t wl\_display\_next\_serial (struct wl\_display \* display)

Get the next serial number

**Parameters**

*display* The display object

This function increments the display serial number and returns the new value.

### int wl\_display\_prepare\_read (struct wl\_display \* display)

Prepare to read events from the display's file descriptor

**Parameters**

*display* The display context object

**Returns**

0 on success or -1 if event queue was not empty

This function does the same thing as **wl\_display\_prepare\_read\_queue()** with the default queue passed as the queue.

**See also**

**wl\_display\_prepare\_read\_queue**

### int wl\_display\_prepare\_read\_queue (struct wl\_display \* display, struct wl\_event\_queue \* queue)

Prepare to read events from the display's file descriptor to a queue

**Parameters**

*display* The display context object \
 *queue* The event queue to use

**Returns**

0 on success or -1 if event queue was not empty

This function (or **wl\_display\_prepare\_read()**) must be called before reading from the file descriptor using **wl\_display\_read\_events()**. Calling **wl\_display\_prepare\_read\_queue()** announces the calling thread's intention to read and ensures that until the thread is ready to read and calls **wl\_display\_read\_events()**, no other thread will read from the file descriptor. This only succeeds if the event queue is empty, and if not -1 is returned and errno set to EAGAIN.

If a thread successfully calls **wl\_display\_prepare\_read\_queue()**, it must either call **wl\_display\_read\_events()** when it's ready or cancel the read intention by calling **wl\_display\_cancel\_read()**.

Use this function before polling on the display fd or integrate the fd into a toolkit event loop in a race-free way. A correct usage would be (with most error checking left out):

```
while (wl_display_prepare_read_queue(display, queue) != 0)
        wl_display_dispatch_queue_pending(display, queue);
wl_display_flush(display);
ret = poll(fds, nfds, -1);
if (has_error(ret))
        wl_display_cancel_read(display);
else
        wl_display_read_events(display);
wl_display_dispatch_queue_pending(display, queue);
```

Here we call **wl\_display\_prepare\_read\_queue()**, which ensures that between returning from that call and eventually calling **wl\_display\_read\_events()**, no other thread will read from the fd and queue events in our queue. If the call to **wl\_display\_prepare\_read\_queue()** fails, we dispatch the pending events and try again until we're successful.

The **wl\_display\_prepare\_read\_queue()** function doesn't acquire exclusive access to the display's fd. It only registers that the thread calling this function has intention to read from fd. When all registered readers call **wl\_display\_read\_events()**, only one (at random) eventually reads and queues the events and the others are sleeping meanwhile. This way we avoid races and still can read from more threads.

**See also**

**wl\_display\_cancel\_read()**, **wl\_display\_read\_events()**, **wl\_display\_prepare\_read()**

### int wl\_display\_read\_events (struct wl\_display \* display)

Read events from display file descriptor

**Parameters**

*display* The display context object

**Returns**

0 on success or -1 on error. In case of error errno will be set accordingly

Calling this function will result in data available on the display file descriptor being read and read events will be queued on their corresponding event queues.

Before calling this function, depending on what thread it is to be called from, **wl\_display\_prepare\_read\_queue()** or **wl\_display\_prepare\_read()** needs to be called. See **wl\_display\_prepare\_read\_queue()** for more details.

When being called at a point where other threads have been prepared to read (using **wl\_display\_prepare\_read\_queue()** or **wl\_display\_prepare\_read()**) this function will sleep until all other prepared threads have either been cancelled (using **wl\_display\_cancel\_read()**) or them self entered this function. The last thread that calls this function will then read and queue events on their corresponding event queues, and finally wake up all other **wl\_display\_read\_events()** calls causing them to return.

If a thread cancels a read preparation when all other threads that have prepared to read has either called **wl\_display\_cancel\_read()** or **wl\_display\_read\_events()**, all reader threads will return without having read any data.

To dispatch events that may have been queued, call **wl\_display\_dispatch\_pending()** or **wl\_display\_dispatch\_queue\_pending()**.

**See also**

**wl\_display\_prepare\_read()**, **wl\_display\_cancel\_read()**, **wl\_display\_dispatch\_pending()**, **wl\_display\_dispatch()**

### int wl\_display\_remove\_socket\_fd (struct wl\_display \* display, int sock\_fd)

Remove a socket fd from the Wayland display.

**Parameters**

*display* Wayland display from which the socket should be removed. \
 *sock\_fd* The socket file descriptor to be removed.

**Returns**

0 if success. -1 if failed.

Remove a socket fd previously added via **wl\_display\_add\_socket\_fd()**.

**Since**

1\.25.90

### int wl\_display\_roundtrip (struct wl\_display \* display)

Block until all pending request are processed by the server

**Parameters**

*display* The display context object

**Returns**

The number of dispatched events on success or -1 on failure

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning.

This function uses **wl\_display\_dispatch\_queue()** internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

**Note**

This function may dispatch other events being received on the default queue.

### int wl\_display\_roundtrip\_queue (struct wl\_display \* display, struct wl\_event\_queue \* queue)

Block until all pending request are processed by the server

**Parameters**

*display* The display context object \
 *queue* The queue on which to run the roundtrip

**Returns**

The number of dispatched events on success or -1 on failure

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning.

This function uses **wl\_display\_dispatch\_queue()** internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

**Note**

This function may dispatch other events being received on the given queue.

**See also**

**wl\_display\_roundtrip()**

### void wl\_display\_set\_default\_max\_buffer\_size (struct wl\_display \* display, size\_t max\_buffer\_size)

Sets the default maximum size for connection buffers of new clients

**Parameters**

*display* The display object \
 **max\_buffer\_size The default maximum size of the connection buffers**

**This function sets the default size of the internal connection buffers for new clients. It doesn't change the buffer size for existing wl\_client.**

**The connection buffer size of an existing wl\_client can be adjusted using wl\_client\_set\_max\_buffer\_size().**

**The actual size of the connection buffers is a power of two, the requested** *max\_buffer\_size* **is therefore rounded up to the nearest power of two value.**

**The minimum buffer size is 4096.**

**See also**

**wl\_client\_set\_max\_buffer\_size**

**Since**

**1.22.90**

### void wl\_display\_set\_global\_filter (struct wl\_display \* display, wl\_display\_global\_filter\_func\_t filter, void \* data)

**Set a filter function for global objects**

**Parameters**

*display* **The Wayland display object.** \
 *filter* **The global filter function.** \
 *data* **User data to be associated with the global filter.**

**Set a filter for the wl\_display to advertise or hide global objects to clients. The set filter will be used during wl\_global advertisement to determine whether a global object should be advertised to a given client, and during wl\_global binding to determine whether a given client should be allowed to bind to a global.**

**Clients that try to bind to a global that was filtered out will have an error raised.**

**Setting the filter NULL will result in all globals being advertised to all clients. The default is no filter.**

**The filter should be installed before any client connects and should always take the same decision given a client and a global. Not doing so will result in inconsistent filtering and broken wl\_registry event sequences.**

### void wl\_display\_set\_max\_buffer\_size (struct wl\_display \* display, size\_t max\_buffer\_size)

**Adjust the maximum size of the client connection buffers**

**Parameters**

*display* **The display context object** \
 **max\_buffer\_size The maximum size of the connection buffers**

**Client buffers are unbounded by default. This function sets a limit to the size of the connection buffers.**

**A value of 0 for** *max\_buffer\_size* **requests the buffers to be unbounded.**

**The actual size of the connection buffers is a power of two, the requested** *max\_buffer\_size* **is therefore rounded up to the nearest power of two value.**

**Lowering the maximum size may not take effect immediately if the current content of the buffer does not fit within the new size limit.**

**Since**

**1.22.90**

## Field Documentation

### struct wl\_array wl\_display::additional\_shm\_formats

### struct wl\_list wl\_display::client\_list

### struct wl\_priv\_signal wl\_display::create\_client\_signal

### struct wl\_priv\_signal wl\_display::destroy\_signal

### wl\_display\_global\_filter\_func\_t wl\_display::global\_filter

### void\* wl\_display::global\_filter\_data

### struct wl\_list wl\_display::global\_list

### struct wl\_event\_loop\* wl\_display::loop

### size\_t wl\_display::max\_buffer\_size

### uint32\_t wl\_display::next\_global\_name

### struct wl\_list wl\_display::protocol\_loggers

### struct wl\_list wl\_display::registry\_resource\_list

### bool wl\_display::run

### uint32\_t wl\_display::serial

### struct wl\_list wl\_display::socket\_list

### struct wl\_event\_source\* wl\_display::term\_source

### int wl\_display::terminate\_efd

## Author

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