.TH "wl_shm_buffer" 3 "Version 1.26.0" "Wayland" \" -*- nroff -*- .ad l .nh .SH NAME wl_shm_buffer \- A SHM buffer\&. .SH SYNOPSIS .br .PP .SS "Public Member Functions" .in +1c .ti -1c .RI "void * \fBwl_shm_buffer_get_data\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .ti -1c .RI "struct \fBwl_shm_buffer\fP * \fBwl_shm_buffer_ref\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .ti -1c .RI "void \fBwl_shm_buffer_unref\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .ti -1c .RI "struct \fBwl_shm_pool\fP * \fBwl_shm_buffer_ref_pool\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .ti -1c .RI "void \fBwl_shm_buffer_begin_access\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .ti -1c .RI "void \fBwl_shm_buffer_end_access\fP (struct \fBwl_shm_buffer\fP *buffer)" .br .in -1c .SS "Data Fields" .in +1c .ti -1c .RI "struct \fBwl_resource\fP * \fBresource\fP" .br .ti -1c .RI "int \fBinternal_refcount\fP" .br .ti -1c .RI "int \fBexternal_refcount\fP" .br .ti -1c .RI "struct \fBwl_client\fP * \fBclient\fP" .br .ti -1c .RI "struct \fBwl_listener\fP \fBclient_destroy_listener\fP" .br .ti -1c .RI "int32_t \fBwidth\fP" .br .ti -1c .RI "int32_t \fBheight\fP" .br .ti -1c .RI "int32_t \fBstride\fP" .br .ti -1c .RI "uint32_t \fBformat\fP" .br .ti -1c .RI "int \fBoffset\fP" .br .ti -1c .RI "struct \fBwl_shm_pool\fP * \fBpool\fP" .br .in -1c .SH "Detailed Description" .PP A SHM buffer\&. \fBwl_shm_buffer\fP provides a helper for accessing the contents of a wl_buffer resource created via the wl_shm interface\&. .PP A \fBwl_shm_buffer\fP becomes invalid as soon as its \fBwl_resource\fP is destroyed\&. .SH "Member Function Documentation" .PP .SS "void wl_shm_buffer_begin_access (struct \fBwl_shm_buffer\fP * buffer)" Mark that the given SHM buffer is about to be accessed .PP \fBParameters\fP .RS 4 \fIbuffer\fP The SHM buffer .RE .PP 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 \fBwl_shm_buffer_end_access()\fP afterwards\&. This will install a signal handler for SIGBUS which will prevent the compositor from crashing\&. .PP 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\&. .PP 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 \fBwl_shm_buffer_end_access()\fP 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\&. .PP 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 \fBwl_shm_buffer_end_access()\fP must match the number of calls to \fBwl_shm_buffer_begin_access()\fP\&. These functions are thread-safe and it is allowed to simultaneously access different buffers or the same buffer from multiple threads\&. .SS "void wl_shm_buffer_end_access (struct \fBwl_shm_buffer\fP * buffer)" Ends the access to a buffer started by \fBwl_shm_buffer_begin_access()\fP .PP \fBParameters\fP .RS 4 \fIbuffer\fP The SHM buffer .RE .PP This should be called after \fBwl_shm_buffer_begin_access()\fP 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\&. .SS "void * wl_shm_buffer_get_data (struct \fBwl_shm_buffer\fP * buffer)" Get a pointer to the memory for the SHM buffer .PP \fBParameters\fP .RS 4 \fIbuffer\fP The buffer object .RE .PP Returns a pointer which can be used to read the data contained in the given SHM buffer\&. .PP 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 \fBwl_shm_buffer_begin_access()\fP and \fBwl_shm_buffer_end_access()\fP around code that reads from the memory\&. .SS "struct \fBwl_shm_buffer\fP * wl_shm_buffer_ref (struct \fBwl_shm_buffer\fP * buffer)" Reference a shm_buffer .PP \fBParameters\fP .RS 4 \fIbuffer\fP The buffer object .RE .PP Returns a pointer to the buffer and increases the refcount\&. .PP The compositor must remember to call \fBwl_shm_buffer_unref()\fP when it no longer needs the reference to ensure proper destruction of the buffer\&. .PP \fBSee also\fP .RS 4 \fBwl_shm_buffer_unref\fP .RE .PP .SS "struct \fBwl_shm_pool\fP * wl_shm_buffer_ref_pool (struct \fBwl_shm_buffer\fP * buffer)" Get a reference to a shm_buffer's \fBshm_pool\fP .PP \fBParameters\fP .RS 4 \fIbuffer\fP The buffer object .RE .PP Returns a pointer to a buffer's \fBshm_pool\fP and increases the \fBshm_pool\fP refcount\&. .PP The compositor must remember to call \fBwl_shm_pool_unref()\fP when it no longer needs the reference to ensure proper destruction of the pool\&. .PP \fBSee also\fP .RS 4 \fBwl_shm_pool_unref\fP .RE .PP .SS "void wl_shm_buffer_unref (struct \fBwl_shm_buffer\fP * buffer)" Unreference a shm_buffer .PP \fBParameters\fP .RS 4 \fIbuffer\fP The buffer object .RE .PP Drops a reference to a buffer object\&. .PP This is only necessary if the compositor has explicitly taken a reference with \fBwl_shm_buffer_ref()\fP, otherwise the buffer will be automatically destroyed when appropriate\&. .PP \fBSee also\fP .RS 4 \fBwl_shm_buffer_ref\fP .RE .PP .SH "Field Documentation" .PP .SS "struct \fBwl_client\fP* wl_shm_buffer::client" .SS "struct \fBwl_listener\fP wl_shm_buffer::client_destroy_listener" .SS "int wl_shm_buffer::external_refcount" .SS "uint32_t wl_shm_buffer::format" .SS "int32_t wl_shm_buffer::height" .SS "int wl_shm_buffer::internal_refcount" .SS "int wl_shm_buffer::offset" .SS "struct \fBwl_shm_pool\fP* wl_shm_buffer::pool" .SS "struct \fBwl_resource\fP* wl_shm_buffer::resource" .SS "int32_t wl_shm_buffer::stride" .SS "int32_t wl_shm_buffer::width" .SH "Author" .PP Generated automatically by Doxygen for Wayland from the source code\&.