voidwl_shm_buffer_begin_access(structwl_shm_buffer*buffer)
Mark that the given SHM buffer is about to be accessed
Parametersbuffer 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 pool.
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.
voidwl_shm_buffer_end_access(structwl_shm_buffer*buffer)
Ends the access to a buffer started by wl_shm_buffer_begin_access()Parametersbuffer 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(structwl_shm_buffer*buffer)
Get a pointer to the memory for the SHM buffer
Parametersbuffer 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.
structwl_shm_buffer*wl_shm_buffer_ref(structwl_shm_buffer*buffer)
Reference a shm_buffer
Parametersbuffer The buffer object
Returns a pointer to the buffer and increases the refcount.
The compositor must remember to call wl_shm_buffer_unref() when it no longer needs the reference to
ensure proper destruction of the buffer.
Seealsowl_shm_buffer_unrefstructwl_shm_pool*wl_shm_buffer_ref_pool(structwl_shm_buffer*buffer)
Get a reference to a shm_buffer's shm_poolParametersbuffer 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.
Seealsowl_shm_pool_unrefvoidwl_shm_buffer_unref(structwl_shm_buffer*buffer)
Unreference a shm_buffer
Parametersbuffer The buffer object
Drops a reference to a buffer object.
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.
Seealsowl_shm_buffer_ref
Install Now
PNG Icons
