wl_shm_buffer(3) Wayland wl_shm_buffer(3)
NAME
wl_shm_buffer - A SHM buffer.
SYNOPSIS
Public Member Functions
void * wl_shm_buffer_get_data (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
int32_t width
int32_t height
int32_t stride
uint32_t format
int offset
struct wl_shm_pool * pool
Detailed Description
A SHM buffer.
wl_shm_buffer provides a helper for accessing the contents of a
wl_buffer resource created via the wl_shm interface.
A wl_shm_buffer becomes invalid as soon as its wl_resource is
destroyed.
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
An SHM buffer is a memory-mapped file given by the client. According to
POSIX, reading from a memory-mapped region that extends off the end of
the file will cause a SIGBUS signal to be generated. Normally this
would cause the compositor to terminate. In order to make the
compositor robust against clients that change the size of the
underlying file or lie about its size, you should protect access to the
buffer by calling this function before reading from the memory and call
wl_shm_buffer_end_access afterwards. This will install a signal handler
for SIGBUS which will prevent the compositor from crashing.
After calling this function the signal handler will remain installed
for the lifetime of the compositor process. Note that this function
will not work properly if the compositor is also installing its own
handler for SIGBUS.
If a SIGBUS signal is received for an address within the range of the
SHM pool of the given buffer then the client will be sent an error
event when wl_shm_buffer_end_access is called. If the signal is for an
address outside that range then the signal handler will reraise the
signal which would will likely cause the compositor to terminate.
It is safe to nest calls to these functions as long as the nested calls
are all accessing the same buffer. The number of calls to
wl_shm_buffer_end_access must match the number of calls to
wl_shm_buffer_begin_access. These functions are thread-safe and it is
allowed to simultaneously access different buffers or the same buffer
from multiple threads.
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
This should be called after wl_shm_buffer_begin_access once the buffer
is no longer being accessed. If a SIGBUS signal was generated in-
between these two calls then the resource for the given buffer will be
sent an error.
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 which can be used to read the data contained in the
given SHM buffer.
As this buffer is memory-mapped, reading from it may generate SIGBUS
signals. This can happen if the client claims that the buffer is larger
than it is or if something truncates the underlying file. To prevent
this signal from causing the compositor to crash you should call
wl_shm_buffer_begin_access and wl_shm_buffer_end_access around code
that reads from the memory.
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.
The compositor must remember to call wl_shm_pool_unref when it no
longer needs the reference to ensure proper destruction of the pool.
See also
wl_shm_pool_unref
Field Documentation
uint32_t wl_shm_buffer::format
int32_t wl_shm_buffer::height
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.
Version 1.20.0 Wed Sep 14 2022 wl_shm_buffer(3)
Generated by dwww version 1.14 on Mon Feb 3 08:33:23 CET 2025.