wl_client(3)

📦
version 1.26.0 · 15 versions
, in fedora 43, ubuntu stonking

💖 wl_client 💖

okay bestie, gather round, because today we're getting into wl_client(3) — a Library Functions Manual situation, and honestly? it's giving backstage-pass-to-the-compositor energy. 🎀

✨ NAME ✨

wl_client — no cap, that's the whole name, she's mysterious like that 💅

🌈 SYNOPSIS 🌈

🫶 Public Member Functions

void wl_client_flush (struct wl_client *client)
struct wl_display * wl_client_get_display (struct wl_client *client)
void wl_client_get_credentials (const struct wl_client *client, pid_t
    *pid, uid_t *uid, gid_t *gid)
int wl_client_get_fd (struct wl_client *client)
struct wl_resource * wl_client_get_object (struct wl_client *client,
    uint32_t id)
void wl_client_post_implementation_error (struct wl_client *client, char
    const *msg,...)
void wl_client_add_destroy_listener (struct wl_client *client, struct
    wl_listener *listener)
void wl_client_add_destroy_late_listener (struct wl_client *client,
    struct wl_listener *listener)
struct wl_list * wl_client_get_link (struct wl_client *client)
struct wl_client * wl_client_from_link (struct wl_list *link)
void wl_client_add_resource_created_listener (struct wl_client *client,
    struct wl_listener *listener)
void wl_client_for_each_resource (struct wl_client *client,
    wl_client_for_each_resource_iterator_func_t iterator, void
    *user_data)
void wl_client_set_max_buffer_size (struct wl_client *client, size_t
    max_buffer_size)

🍓 Data Fields

struct wl_connection * connection
struct wl_event_source * source
struct wl_display * display
struct wl_resource * display_resource
struct wl_list link
struct wl_map objects
struct wl_priv_signal destroy_signal
struct wl_priv_signal destroy_late_signal
pid_t pid
uid_t uid
gid_t gid
bool error
struct wl_priv_signal resource_created_signal
void * data
wl_user_data_destroy_func_t data_dtor

🌸 Member Function Documentation 🌸

void wl_client_add_destroy_late_listener (struct wl_client * client, struct wl_listener * listener)

Add a listener to be called at the end of wl_client destruction — the afterparty listener, if you will. 🎉

The listener you hand over gets called when wl_client destroy is nearly complete — like, after all of that client's resources have already been destroyed. last one out, turn off the lights energy fr fr.

There is no requirement to remove the link of the wl_listener when the signal is emitted. so don't stress about cleanup, she handles it. 🫶

Since 1.22.0

void wl_client_add_destroy_listener (struct wl_client * client, struct wl_listener * listener)

Add a listener to be called at the beginning of wl_client destruction — the first one in listener this time. 👑

The listener provided will be called when wl_client destroy has begun, before any of that client's resources have been destroyed.

There is no requirement to remove the link of the wl_listener when the signal is emitted.

void wl_client_add_resource_created_listener (struct wl_client * client, struct wl_listener * listener)

Add a listener for the client's resource creation signal ✨ baby shower for new resources, basically.

Parameters

  • client — The client object
  • listener — The listener to be added

When a new resource is created for this client the listener will be notified, carrying the new resource as the data argument. new resource drop 🎀

void wl_client_flush (struct wl_client * client)

Flush pending events to the client — sending the texts she's been typing for 20 minutes. 📤

Parameters

  • client — The client object

Events sent to clients are queued in a buffer and written to the socket later — typically when the compositor has handled all requests and goes back to block in the event loop. This function flushes all queued up events for a client immediately. no more leaving them on read, bestie. 💅

void wl_client_for_each_resource (struct wl_client * client, wl_client_for_each_resource_iterator_func_t iterator, void * user_data)

Iterate over all the resources of a client — the scroll-through-the-whole-finsta-grid function. 🦋

Parameters

  • client — The client object
  • iterator — The iterator function
  • user_data — The user data pointer

The function pointed by iterator will be called for each resource owned by the client. The user_data will be passed as the second argument of the iterator function. If the iterator function returns WL_ITERATOR_CONTINUE the iteration will continue, if it returns WL_ITERATOR_STOP it will stop. keep scrolling vs. stop scrolling, iconic duo.

Creating and destroying resources while iterating is safe, but new resources may or may not be picked up by the iterator. (she's a little unpredictable, it's fine, we love her.) 😌

See also wl_iterator_result

Get a wl_client by its link — reverse-engineering the @ from the tag. 🔍

Parameters

  • link — The link of a wl_client

See also wl_client_for_each()

wl_display_get_client_list()

wl_client_get_link()

void wl_client_get_credentials (const struct wl_client * client, pid_t * pid, uid_t * uid, gid_t * gid)

Return Unix credentials for the client — ID check at the door. 🪪

Parameters

  • client — The display object
  • pid — Returns the process ID
  • uid — Returns the user ID
  • gid — Returns the group ID

This function returns the process ID, the user ID and the group ID for the given client. The credentials come from getsockopt() with SO_PEERCRED, on the client socket fd. All the pointers can be NULL, if the caller is not interested in a particular ID. (zero-pressure invite, you can skip the RSVP.)

⚠️ Note, process IDs are subject to race conditions and are not a reliable way to identify a client. do not be trusting a pid like it's a government ID, bestie, it's more like a screenshotted story. 💀

Be aware that for clients that a compositor forks and execs and then connects using socketpair(), this function will return the credentials for the compositor. The credentials for the socketpair are set at creation time in the compositor. so yeah, sometimes the ID check is checking the wrong person. 🙈

struct wl_display * wl_client_get_display (struct wl_client * client)

Get the display object for the given client 🖥️

Parameters

  • client — The client object

Returns The display object the client is associated with.

int wl_client_get_fd (struct wl_client * client)

Get the file descriptor for the client 🔌

Parameters

  • client — The display object

Returns The file descriptor to use for the connection

This function returns the file descriptor for the given client.

🚨 Be sure to use the file descriptor from the client for inspection only. If the caller does anything to the file descriptor that changes its state, it will likely cause problems. look, don't touch — museum rules. 🖼️

See also wl_client_get_credentials(). It is recommended that you evaluate whether wl_client_get_credentials() can be applied to your use case instead of this function.

If you would like to distinguish just between the client and the compositor itself from the client's request, it can be done by getting the client credentials and by checking the PID of the client and the compositor's PID. Regarding the case in which the socketpair() is being used, you need to be careful. Please note the documentation for wl_client_get_credentials().

This function can be used for a compositor to validate a request from a client if there are additional information provided from the client's file descriptor. For instance, suppose you can get the security contexts from the client's file descriptor. The compositor can validate the client's request with the contexts and make a decision whether it permits or deny it. security guard behavior, honestly slay.

Get the link by which a client is inserted in the client list 🔗

Parameters

  • client — The client object

See also wl_client_for_each()

wl_display_get_client_list()

wl_client_from_link()

struct wl_resource * wl_client_get_object (struct wl_client * client, uint32_t id)

Look up an object in the client name space 👀

Parameters

  • client — The client object
  • id — The object id

Returns The object or NULL if there is not object for the given ID

This looks up an object in the client object name space by its object ID. (yes the original says "if there is not object", she's typing fast, we're not fixing her texts.) 💅

void wl_client_post_implementation_error (struct wl_client * client, char const * msg, ...)

Report an internal server error 💀

Parameters

  • client — The client object
  • msg — A printf-style format string
  • ... — Format string arguments

Report an unspecified internal implementation error and disconnect the client. yeah. it's giving "we need to talk." 🚪

void wl_client_set_max_buffer_size (struct wl_client * client, size_t max_buffer_size)

Adjust the maximum size of the client connection buffers 📏

Parameters

  • client — The client object
  • max_buffer_size — The maximum size of the connection buffers

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. math girlies rise. 🧮✨

Lowering the maximum size may not take effect immediately if the current content of the buffer does not fit within the new size limit. (the outfit change is pending, the current look is still on.) 😭

The minimum buffer size is 4096. The default buffers size can be set using wl_display_set_default_max_buffer_size().

See also wl_display_set_default_max_buffer_size()

Since 1.22.90

🦋 Field Documentation 🦋

  • struct wl_connection* wl_client::connection
  • void* wl_client::data
  • wl_user_data_destroy_func_t wl_client::data_dtor
  • struct wl_priv_signal wl_client::destroy_late_signal
  • struct wl_priv_signal wl_client::destroy_signal
  • struct wl_display* wl_client::display
  • struct wl_resource* wl_client::display_resource
  • bool wl_client::error
  • gid_t wl_client::gid
  • struct wl_list wl_client::link
  • struct wl_map wl_client::objects
  • pid_t wl_client::pid
  • struct wl_priv_signal wl_client::resource_created_signal
  • struct wl_event_source* wl_client::source
  • uid_t wl_client::uid

👑 Author 👑

Generated automatically by Doxygen for Wayland from the source code. (not a human author, just the compiler's little scribe, and honestly? she ate. 💅)

and that's the whole page, bestie!! this was Wayland, Version 1.26.0, in the wl_client(3) section — go forth and be the main character of your own event loop. 🫶✨🎀🦋

📦 where this page comes from