wl_shm_buffer(3)

🌸 wl_shm_buffer 🌸

okay bestie, pull up a chair because we're doing a library functions manual deep-dive 💅 this is the wl_shm_buffer page, part of the Wayland crew, and it's genuinely so useful once it clicks. iykyk.

---

✨ NAME ✨

wl_shm_buffer — A SHM buffer. that's it, that's the whole vibe. a buffer. a shared-memory one. iconic behavior honestly 💖

---

🎀 SYNOPSIS 🎀

💅 Public Member Functions

void * wl_shm_buffer_get_data (struct wl_shm_buffer *buffer)
struct wl_shm_buffer * wl_shm_buffer_ref (struct wl_shm_buffer *buffer)
void wl_shm_buffer_unref (struct wl_shm_buffer *buffer)
struct wl_shm_pool * wl_shm_buffer_ref_pool (struct wl_shm_buffer
    *buffer)
void wl_shm_buffer_begin_access (struct wl_shm_buffer *buffer)
void wl_shm_buffer_end_access (struct wl_shm_buffer *buffer)

🦋 Data Fields

struct wl_resource * resource
int internal_refcount
int external_refcount
struct wl_client * client
struct wl_listener client_destroy_listener
int32_t width
int32_t height
int32_t stride
uint32_t format
int offset
struct wl_shm_pool * pool

---

🌈 Detailed Description 🌈

okay so. A SHM buffer. that's the energy. 🫶

wl_shm_buffer is out here being a lil helper for getting at the contents of a wl_buffer resource that some client made through the wl_shm interface. very "let me hold this for you" of it, honestly.

⚠️ real talk bestie: a wl_shm_buffer becomes invalid the instant its wl_resource is destroyed. like, gone. no takebacks. do not be caught reading from it after that, fr fr 😭

---

👑 Member Function Documentation 👑

void wl_shm_buffer_begin_access (struct wl_shm_buffer * buffer)

Mark that the given SHM buffer is about to be accessed ✨

Parameters

• buffer — The SHM buffer

so here's the situation. an SHM buffer is a memory-mapped file handed over by the client. and according to POSIX, if you read from a memory-mapped region that extends off the end of the file? you get a SIGBUS signal. and normally that would just straight-up terminate the compositor. not slay. not the move. 💀

so to make the compositor robust against clients that resize the underlying file or just lie about its size, you should wrap your reads in this: call this function before reading from the memory, and call wl_shm_buffer_end_access() after. that installs a signal handler for SIGBUS which keeps the compositor from crashing. protective queen behavior. 🧚

after you call this function, that signal handler stays installed for the lifetime of the compositor process. and heads up — this will not work properly if the compositor is also installing its own handler for SIGBUS. pick a lane bestie. 🙈

if a SIGBUS signal comes in for an address within the range of the SHM pool of the given buffer, then the client gets sent an error event when wl_shm_buffer_end_access() is called. but if the signal is for an address outside that range, the signal handler will reraise the signal, which would likely cause the compositor to terminate. 😳 so. yeah. know your range.

it is safe to nest calls to these functions, as long as the nested calls are all accessing the same pool. the number of calls to wl_shm_buffer_end_access() must match the number of calls to wl_shm_buffer_begin_access(). count them. for real. these functions are thread-safe, and it's allowed to simultaneously access different buffers — or the same buffer — from multiple threads. multitasking queen 💅

void wl_shm_buffer_end_access (struct wl_shm_buffer * buffer)

Ends the access to a buffer started by wl_shm_buffer_begin_access() 🌸

Parameters

• buffer — The SHM buffer

call this after wl_shm_buffer_begin_access() once you're done touching the buffer. if a SIGBUS signal was generated in-between those two calls, then the resource for the given buffer will be sent an error. consequences! ✨

void * wl_shm_buffer_get_data (struct wl_shm_buffer * buffer)

Get a pointer to the memory for the SHM buffer 🎀

Parameters

• buffer — The buffer object

returns a pointer you can use to read the data contained in the given SHM buffer. very giving.

but because this buffer is memory-mapped, reading from it may generate SIGBUS signals. this can happen if the client claims the buffer is bigger than it actually is, or if something truncates the underlying file. to keep that signal from crashing the compositor, you should call wl_shm_buffer_begin_access() and wl_shm_buffer_end_access() around any code that reads from the memory. wrap it up, keep it safe 🫶

struct wl_shm_buffer * wl_shm_buffer_ref (struct wl_shm_buffer * buffer)

Reference a shm_buffer 🔥

Parameters

• buffer — The buffer object

returns a pointer to the buffer and increases the refcount. it's giving commitment.

the compositor must remember to call wl_shm_buffer_unref() when it no longer needs the reference, so the buffer gets properly destroyed. don't leave it hanging.

See also

• wl_shm_buffer_unref

struct wl_shm_pool * wl_shm_buffer_ref_pool (struct wl_shm_buffer * buffer)

Get a reference to a shm_buffer's shm_pool 🌊

Parameters

• buffer — The buffer object

returns a pointer to a buffer's shm_pool and increases the shm_pool refcount. pool party, but make it responsible 💖

the compositor must remember to call wl_shm_pool_unref() when it no longer needs the reference, so the pool gets properly destroyed.

See also

• wl_shm_pool_unref

void wl_shm_buffer_unref (struct wl_shm_buffer * buffer)

Unreference a shm_buffer 💅

Parameters

• buffer — The buffer object

drops a reference to a buffer object. letting it go, respectfully.

this is only necessary if the compositor has explicitly taken a reference with wl_shm_buffer_ref(). otherwise the buffer will be automatically destroyed when appropriate. no manual labor required, she handles herself.

See also

• wl_shm_buffer_ref

---

💜 Field Documentation 💜

struct wl_client* wl_shm_buffer::client

struct wl_listener wl_shm_buffer::client_destroy_listener

int wl_shm_buffer::external_refcount

uint32_t wl_shm_buffer::format

int32_t wl_shm_buffer::height

int wl_shm_buffer::internal_refcount

int wl_shm_buffer::offset

struct wl_shm_pool* wl_shm_buffer::pool

struct wl_resource* wl_shm_buffer::resource

int32_t wl_shm_buffer::stride

int32_t wl_shm_buffer::width

---

⭐ Author ⭐

Generated automatically by Doxygen for Wayland from the source code. (not a human, just a very efficient robot bestie 🤖✨)

---

okay that's the whole page, you ate that 🍓 thanks for reading all the way to the end, ily. this was Wayland, Version 1.26.0, and it's the wl_shm_buffer(3) page. go forth and buffer responsibly, bestie 💖🎀🦋