---
name: "wl_proxy"
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_proxy"
---

# wl\_proxy(3)

Represents a protocol object on the client side.

## NAME

wl\_proxy - Represents a protocol object on the client side.

## SYNOPSIS

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

### Public Member Functions

struct **wl\_proxy** \* **wl\_proxy\_create** (struct **wl\_proxy** \*factory, const struct **wl\_interface** \*interface)\
 void **wl\_proxy\_destroy** (struct **wl\_proxy** \*proxy)\
 int **wl\_proxy\_add\_listener** (struct **wl\_proxy** \*proxy, void(\*\*implementation)(void), void \*data)\
 const void \* **wl\_proxy\_get\_listener** (struct **wl\_proxy** \*proxy)\
 int **wl\_proxy\_add\_dispatcher** (struct **wl\_proxy** \*proxy, **wl\_dispatcher\_func\_t** dispatcher, const void \*implementation, void \*data)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_array\_constructor** (struct **wl\_proxy** \*proxy, uint32\_t opcode, union **wl\_argument** \*args, const struct **wl\_interface** \*interface)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_array\_constructor\_versioned** (struct **wl\_proxy** \*proxy, uint32\_t opcode, union **wl\_argument** \*args, const struct **wl\_interface** \*interface, uint32\_t version)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_flags** (struct **wl\_proxy** \*proxy, uint32\_t opcode, const struct **wl\_interface** \*interface, uint32\_t version, uint32\_t flags,...)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_array\_flags** (struct **wl\_proxy** \*proxy, uint32\_t opcode, const struct **wl\_interface** \*interface, uint32\_t version, uint32\_t flags, union **wl\_argument** \*args)\
 void **wl\_proxy\_marshal** (struct **wl\_proxy** \*proxy, uint32\_t opcode,...)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_constructor** (struct **wl\_proxy** \*proxy, uint32\_t opcode, const struct **wl\_interface** \*interface,...)\
 struct **wl\_proxy** \* **wl\_proxy\_marshal\_constructor\_versioned** (struct **wl\_proxy** \*proxy, uint32\_t opcode, const struct **wl\_interface** \*interface, uint32\_t version,...)\
 void **wl\_proxy\_marshal\_array** (struct **wl\_proxy** \*proxy, uint32\_t opcode, union **wl\_argument** \*args)\
 void **wl\_proxy\_set\_user\_data** (struct **wl\_proxy** \*proxy, void \*user\_data)\
 void \* **wl\_proxy\_get\_user\_data** (struct **wl\_proxy** \*proxy)\
 uint32\_t **wl\_proxy\_get\_version** (struct **wl\_proxy** \*proxy)\
 uint32\_t **wl\_proxy\_get\_id** (struct **wl\_proxy** \*proxy)\
 void **wl\_proxy\_set\_tag** (struct **wl\_proxy** \*proxy, const char \*const \*tag)\
 const char \*const \* **wl\_proxy\_get\_tag** (struct **wl\_proxy** \*proxy)\
 const char \* **wl\_proxy\_get\_class** (struct **wl\_proxy** \*proxy)\
 const struct **wl\_interface** \* **wl\_proxy\_get\_interface** (struct **wl\_proxy** \*proxy)\
 struct **wl\_display** \* **wl\_proxy\_get\_display** (struct **wl\_proxy** \*proxy)\
 void **wl\_proxy\_set\_queue** (struct **wl\_proxy** \*proxy, struct **wl\_event\_queue** \*queue)\
 const char \* **wl\_event\_queue\_get\_name** (const struct **wl\_event\_queue** \*queue)\
 void \* **wl\_proxy\_create\_wrapper** (void \*proxy)\
 void **wl\_proxy\_wrapper\_destroy** (void \*proxy\_wrapper)\

### Related Symbols

(Note that these are not member symbols.)  #define **WL\_MARSHAL\_FLAG\_DESTROY**   (1 \<\< 0)\

## Detailed Description

Represents a protocol object on the client side.

A **wl\_proxy** acts as a client side proxy to an object existing in the compositor. The proxy is responsible for converting requests made by the clients with **wl\_proxy\_marshal()** into Wayland's wire format. Events coming from the compositor are also handled by the proxy, which will in turn call the handler set with **wl\_proxy\_add\_listener()**.

**Note**

With the exception of function **wl\_proxy\_set\_queue()**, functions accessing a **wl\_proxy** are not normally used by client code. Clients should normally use the higher level interface generated by the scanner to interact with compositor objects.

## Member Function Documentation

### const char \* wl\_event\_queue\_get\_name (const struct wl\_event\_queue \* queue)

Get the name of an event queue

**Parameters**

*queue* The queue to query

Return the human readable name for the event queue

This may be NULL if no name has been set.

### int wl\_proxy\_add\_dispatcher (struct wl\_proxy \* proxy, wl\_dispatcher\_func\_t dispatcher, const void \* implementation, void \* data)

Set a proxy's listener (with dispatcher)

**Parameters**

*proxy* The proxy object \
 *dispatcher* The dispatcher to be used for this proxy \
 *implementation* The dispatcher-specific listener implementation \
 *data* User data to be associated with the proxy

**Returns**

0 on success or -1 on failure

Set proxy's listener to use dispatcher\_func as its dispatcher and dispatcher\_data as its dispatcher-specific implementation and its user data to data. If a listener has already been set, this function fails and nothing is changed.

The exact details of dispatcher\_data depend on the dispatcher used. This function is intended to be used by language bindings, not user code.

proxy must not be a proxy wrapper.

### int wl\_proxy\_add\_listener (struct wl\_proxy \* proxy, void(\*\* implementation )(void), void \* data)

Set a proxy's listener

**Parameters**

*proxy* The proxy object \
 *implementation* The listener to be added to proxy \
 *data* User data to be associated with the proxy

**Returns**

0 on success or -1 on failure

Set proxy's listener to implementation and its user data to data. If a listener has already been set, this function fails and nothing is changed.

implementation is a vector of function pointers. For an opcode n, implementation\[n\] should point to the handler of n for the given object.

proxy must not be a proxy wrapper.

### struct wl\_proxy \* wl\_proxy\_create (struct wl\_proxy \* factory, const struct wl\_interface \* interface)

Create a proxy object with a given interface

**Parameters**

*factory* Factory proxy object \
 *interface* Interface the proxy object should use

**Returns**

A newly allocated proxy object or NULL on failure

This function creates a new proxy object with the supplied interface. The proxy object will have an id assigned from the client id space. The id should be created on the compositor side by sending an appropriate request with **wl\_proxy\_marshal()**.

The proxy will inherit the display and event queue of the factory object.

**Note**

This should not normally be used by non-generated code.

**See also**

**wl\_display**, **wl\_event\_queue**, **wl\_proxy\_marshal()**

### void \* wl\_proxy\_create\_wrapper (void \* proxy)

Create a proxy wrapper for making queue assignments thread-safe

**Parameters**

*proxy* The proxy object to be wrapped

**Returns**

A proxy wrapper for the given proxy or NULL on failure

A proxy wrapper is type of 'struct **wl\_proxy**' instance that can be used when sending requests instead of using the original proxy. A proxy wrapper does not have an implementation or dispatcher, and events received on the object is still emitted on the original proxy. Trying to set an implementation or dispatcher will have no effect but result in a warning being logged.

Setting the proxy queue of the proxy wrapper will make new objects created using the proxy wrapper use the set proxy queue. Even though there is no implementation nor dispatcher, the proxy queue can be changed. This will affect the default queue of new objects created by requests sent via the proxy wrapper.

A proxy wrapper can only be destroyed using **wl\_proxy\_wrapper\_destroy()**.

A proxy wrapper must be destroyed before the proxy it was created from.

If a user reads and dispatches events on more than one thread, it is necessary to use a proxy wrapper when sending requests on objects when the intention is that a newly created proxy is to use a proxy queue different from the proxy the request was sent on, as creating the new proxy and then setting the queue is not thread safe.

For example, a module that runs using its own proxy queue that needs to do display roundtrip must wrap the **wl\_display** proxy object before sending the wl\_display.sync request. For example:

```
struct wl_event_queue *queue = ...;
struct wl_display *wrapped_display;
struct wl_callback *callback;
wrapped_display = wl_proxy_create_wrapper(display);
wl_proxy_set_queue((struct wl_proxy *) wrapped_display, queue);
callback = wl_display_sync(wrapped_display);
wl_proxy_wrapper_destroy(wrapped_display);
wl_callback_add_listener(callback, ...);
```

### void wl\_proxy\_destroy (struct wl\_proxy \* proxy)

Destroy a proxy object

**Parameters**

*proxy* The proxy to be destroyed

proxy must not be a proxy wrapper.

**Note**

This function will abort in response to egregious errors, and will do so with the display lock held. This means SIGABRT handlers must not perform any actions that would attempt to take that lock, or a deadlock would occur.

### const char \* wl\_proxy\_get\_class (struct wl\_proxy \* proxy)

Get the interface name (class) of a proxy object

**Parameters**

*proxy* The proxy object

**Returns**

The interface name of the object associated with the proxy

### struct wl\_display \* wl\_proxy\_get\_display (struct wl\_proxy \* proxy)

Get the display of a proxy object

**Parameters**

*proxy* The proxy object

**Returns**

The **wl\_display** the proxy is associated with

**Since**

1\.23

### uint32\_t wl\_proxy\_get\_id (struct wl\_proxy \* proxy)

Get the id of a proxy object

**Parameters**

*proxy* The proxy object

**Returns**

The id the object associated with the proxy

### const struct wl\_interface \* wl\_proxy\_get\_interface (struct wl\_proxy \* proxy)

Get the interface of a proxy object

**Parameters**

*proxy* The proxy object

**Returns**

The interface of the object associated with the proxy

**Since**

1\.24

### const void \* wl\_proxy\_get\_listener (struct wl\_proxy \* proxy)

Get a proxy's listener

**Parameters**

*proxy* The proxy object

**Returns**

The address of the proxy's listener or NULL if no listener is set

Gets the address to the proxy's listener; which is the listener set with **wl\_proxy\_add\_listener**.

This function is useful in clients with multiple listeners on the same interface to allow the identification of which code to execute.

If **wl\_proxy\_add\_dispatcher** was used, this function returns the dispatcher\_data pointer instead.

### const char \*const \* wl\_proxy\_get\_tag (struct wl\_proxy \* proxy)

Get the tag of a proxy object

See wl\_proxy\_set\_tag for details.

**Parameters**

*proxy* The proxy object

**Since**

1\.17.90

### void \* wl\_proxy\_get\_user\_data (struct wl\_proxy \* proxy)

Get the user data associated with a proxy

**Parameters**

*proxy* The proxy object

**Returns**

The user data associated with proxy

### uint32\_t wl\_proxy\_get\_version (struct wl\_proxy \* proxy)

Get the protocol object version of a proxy object

**Parameters**

*proxy* The proxy object

**Returns**

The protocol object version of the proxy or 0

Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API.

A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object's real version.

**wl\_display**'s version will always return 0.

### void wl\_proxy\_marshal (struct wl\_proxy \* proxy, uint32\_t opcode, ...)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *...* Extra arguments for the given request

This function is similar to **wl\_proxy\_marshal\_constructor()**, except it doesn't create proxies for new-id arguments.

**Note**

This should not normally be used by non-generated code.

**See also**

**wl\_proxy\_create()**

### void wl\_proxy\_marshal\_array (struct wl\_proxy \* proxy, uint32\_t opcode, union wl\_argument \* args)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *args* Extra arguments for the given request

This function is similar to **wl\_proxy\_marshal\_array\_constructor()**, except it doesn't create proxies for new-id arguments.

**Note**

This is intended to be used by language bindings and not in non-generated code.

**See also**

**wl\_proxy\_marshal()**

### struct wl\_proxy \* wl\_proxy\_marshal\_array\_constructor (struct wl\_proxy \* proxy, uint32\_t opcode, union wl\_argument \* args, const struct wl\_interface \* interface)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *args* Extra arguments for the given request \
 *interface* The interface to use for the new proxy

This function translates a request given an opcode, an interface and a **wl\_argument** array to the wire format and writes it to the connection buffer.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent.

**Note**

This is intended to be used by language bindings and not in non-generated code.

**See also**

**wl\_proxy\_marshal()**

### struct wl\_proxy \* wl\_proxy\_marshal\_array\_constructor\_versioned (struct wl\_proxy \* proxy, uint32\_t opcode, union wl\_argument \* args, const struct wl\_interface \* interface, uint32\_t version)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *args* Extra arguments for the given request \
 *interface* The interface to use for the new proxy \
 *version* The protocol object version for the new proxy

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type **wl\_argument**.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

**Note**

This is intended to be used by language bindings and not in non-generated code.

**See also**

**wl\_proxy\_marshal()**

### struct wl\_proxy \* wl\_proxy\_marshal\_array\_flags (struct wl\_proxy \* proxy, uint32\_t opcode, const struct wl\_interface \* interface, uint32\_t version, uint32\_t flags, union wl\_argument \* args)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *interface* The interface to use for the new proxy \
 *version* The protocol object version for the new proxy \
 *flags* Flags that modify marshalling behaviour \
 *args* Extra arguments for the given request

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type **wl\_argument**.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

The flag WL\_MARSHAL\_FLAG\_DESTROY may be passed to ensure the proxy is destroyed atomically with the marshalling in order to prevent races that can occur if the display lock is dropped between the marshal and destroy operations.

**Note**

This is intended to be used by language bindings and not in non-generated code.

**See also**

**wl\_proxy\_marshal\_flags()**

### struct wl\_proxy \* wl\_proxy\_marshal\_constructor (struct wl\_proxy \* proxy, uint32\_t opcode, const struct wl\_interface \* interface, ...)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *interface* The interface to use for the new proxy \
 *...* Extra arguments for the given request

**Returns**

A new **wl\_proxy** for the new\_id argument or NULL on error

This function translates a request given an opcode, an interface and extra arguments to the wire format and writes it to the connection buffer. The types of the extra arguments must correspond to the argument types of the method associated with the opcode in the interface.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent.

**Note**

This should not normally be used by non-generated code.

### struct wl\_proxy \* wl\_proxy\_marshal\_constructor\_versioned (struct wl\_proxy \* proxy, uint32\_t opcode, const struct wl\_interface \* interface, uint32\_t version, ...)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *interface* The interface to use for the new proxy \
 *version* The protocol object version of the new proxy \
 *...* Extra arguments for the given request

**Returns**

A new **wl\_proxy** for the new\_id argument or NULL on error

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

**Note**

This should not normally be used by non-generated code.

### struct wl\_proxy \* wl\_proxy\_marshal\_flags (struct wl\_proxy \* proxy, uint32\_t opcode, const struct wl\_interface \* interface, uint32\_t version, uint32\_t flags, ...)

Prepare a request to be sent to the compositor

**Parameters**

*proxy* The proxy object \
 *opcode* Opcode of the request to be sent \
 *interface* The interface to use for the new proxy \
 *version* The protocol object version of the new proxy \
 *flags* Flags that modify marshalling behaviour \
 *...* Extra arguments for the given request

**Returns**

A new **wl\_proxy** for the new\_id argument or NULL on error

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer.

For new-id arguments, this function will allocate a new **wl\_proxy** and send the ID to the server. The new **wl\_proxy** will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

The flag WL\_MARSHAL\_FLAG\_DESTROY may be passed to ensure the proxy is destroyed atomically with the marshalling in order to prevent races that can occur if the display lock is dropped between the marshal and destroy operations.

**Note**

This should not normally be used by non-generated code.

### void wl\_proxy\_set\_queue (struct wl\_proxy \* proxy, struct wl\_event\_queue \* queue)

Assign a proxy to an event queue

**Parameters**

*proxy* The proxy object \
 *queue* The event queue that will handle this proxy or NULL

Assign proxy to event queue. Events coming from proxy will be queued in queue from now. If queue is NULL, then the display's default queue is set to the proxy.

In order to guarantee proper handing of all events which were queued before the queue change takes effect, it is required to dispatch the proxy's old event queue after setting a new event queue.

This is particularly important for multi-threaded setups, where it is possible for events to be queued to the proxy's old queue from a different thread during the invocation of this function.

To ensure that all events for a newly created proxy are dispatched on a particular queue, it is necessary to use a proxy wrapper if events are read and dispatched on more than one thread. See **wl\_proxy\_create\_wrapper()** for more details.

**Note**

By default, the queue set in proxy is the one inherited from parent.

**See also**

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

### void wl\_proxy\_set\_tag (struct wl\_proxy \* proxy, const char \*const \* tag)

Set the tag of a proxy object

A toolkit or application can set a unique tag on a proxy in order to identify whether an object is managed by itself or some external part.

To create a tag, the recommended way is to define a statically allocated constant char array containing some descriptive string. The tag will be the pointer to the non-const pointer to the beginning of the array.

For example, to define and set a tag on a surface managed by a certain subsystem:

```
    static const char *my_tag = "my tag";
    wl_proxy_set_tag((struct wl_proxy *) surface, &my_tag);
```

Then, in a callback with wl\_surface as an argument, in order to check whether it's a surface managed by the same subsystem.

```
    const char * const *tag;
    tag = wl_proxy_get_tag((struct wl_proxy *) surface);
    if (tag != &my_tag)
    return;
 ...
```

For debugging purposes, a tag should be suitable to be included in a debug log entry, e.g.

```
    const char * const *tag;
    tag = wl_proxy_get_tag((struct wl_proxy *) surface);
    printf("Got a surface with the tag %p (%s)\n",
           tag, (tag && *tag) ? *tag : "");
```

**Parameters**

*proxy* The proxy object \
 *tag* The tag

**Since**

1\.17.90

### void wl\_proxy\_set\_user\_data (struct wl\_proxy \* proxy, void \* user\_data)

Set the user data associated with a proxy

**Parameters**

*proxy* The proxy object \
 *user\_data* The data to be associated with proxy

Set the user data associated with proxy. When events for this proxy are received, user\_data will be supplied to its listener.

### void wl\_proxy\_wrapper\_destroy (void \* proxy\_wrapper)

Destroy a proxy wrapper

**Parameters**

*proxy\_wrapper* The proxy wrapper to be destroyed

## Friends And Related Symbol Documentation

### #define WL\_MARSHAL\_FLAG\_DESTROY (1 \<\< 0) \[related\]

Destroy proxy after marshalling

## Author

Generated automatically by Doxygen for Wayland from the source code.