Differential D21423 Diff 62598 head/lib/libc/sys/shm_open.2

Changeset View

Standalone View

head/lib/libc/sys/shm_open.2

	Show All 22 Lines
	.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND			.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
	.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,			.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
	.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT			.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
	.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd September 24, 2019			.Dd September 26, 2019
	.Dt SHM_OPEN 2			.Dt SHM_OPEN 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm memfd_create , shm_open , shm_unlink			.Nm memfd_create , shm_open , shm_rename, shm_unlink
	.Nd "shared memory object operations"			.Nd "shared memory object operations"
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/types.h			.In sys/types.h
	.In sys/mman.h			.In sys/mman.h
	.In fcntl.h			.In fcntl.h
	.Ft int			.Ft int
	.Fn memfd_create "const char *name" "unsigned int flags"			.Fn memfd_create "const char *name" "unsigned int flags"
	.Ft int			.Ft int
	.Fn shm_open "const char *path" "int flags" "mode_t mode"			.Fn shm_open "const char *path" "int flags" "mode_t mode"
	.Ft int			.Ft int
				.Fn shm_rename "const char path_from" "const char path_to" "int flags"
				.Ft int
	.Fn shm_unlink "const char *path"			.Fn shm_unlink "const char *path"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Fn shm_open			.Fn shm_open
	system call opens (or optionally creates) a			system call opens (or optionally creates) a
	.Tn POSIX			.Tn POSIX
	shared memory object named			shared memory object named
	.Fa path .			.Fa path .
	▲ Show 20 Lines • Show All 51 Lines • ▼ Show 20 Lines
	The new descriptor is set to close during			The new descriptor is set to close during
	.Xr execve 2			.Xr execve 2
	system calls;			system calls;
	see			see
	.Xr close 2			.Xr close 2
	and			and
	.Xr fcntl 2 .			.Xr fcntl 2 .
	.Pp			.Pp
	As a FreeBSD extension,			As a
	the constant			.Fx
				extension, the constant
	.Dv SHM_ANON			.Dv SHM_ANON
	may be used for the			may be used for the
	.Fa path			.Fa path
	argument to			argument to
	.Fn shm_open .			.Fn shm_open .
	In this case, an anonymous, unnamed shared memory object is created.			In this case, an anonymous, unnamed shared memory object is created.
	Since the object has no name,			Since the object has no name,
	it cannot be removed via a subsequent call to			it cannot be removed via a subsequent call to
	.Fn shm_unlink .			.Fn shm_unlink ,
				or moved with a call to
				.Fn shm_rename .
	Instead,			Instead,
	the shared memory object will be garbage collected when the last reference to			the shared memory object will be garbage collected when the last reference to
	the shared memory object is removed.			the shared memory object is removed.
	The shared memory object may be shared with other processes by sharing the			The shared memory object may be shared with other processes by sharing the
	file descriptor via			file descriptor via
	.Xr fork 2			.Xr fork 2
	or			or
	.Xr sendmsg 2 .			.Xr sendmsg 2 .
	Attempting to open an anonymous shared memory object with			Attempting to open an anonymous shared memory object with
	.Dv O_RDONLY			.Dv O_RDONLY
	will fail with			will fail with
	.Er EINVAL .			.Er EINVAL .
	All other flags are ignored.			All other flags are ignored.
	.Pp			.Pp
	The			The
				.Fn shm_rename
				system call atomically removes a shared memory object named
				.Fa path_from
				and relinks it at
				.Fa path_to .
				If another object is already linked at
				.Fa path_to ,
				that object will be unlinked, unless one of the following flags are provided:
				.Bl -tag -offset indent -width Er
				.It Er SHM_RENAME_EXCHANGE
				Atomically exchange the shms at
				.Fa path_from
				and
				.Fa path_to .
				.It Er SHM_RENAME_NOREPLACE
				Return an error if an shm exists at
				.Fa path_to ,
				rather than unlinking it.
				.El
				.Fn shm_rename
				is also a
				.Fx
				extension.
				.Pp
				The
	.Fn shm_unlink			.Fn shm_unlink
	system call removes a shared memory object named			system call removes a shared memory object named
	.Fa path .			.Fa path .
	.Pp			.Pp
	The			The
	.Fn memfd_create			.Fn memfd_create
	function creates an anonymous shared memory object, identical to that created			function creates an anonymous shared memory object, identical to that created
	by			by
	▲ Show 20 Lines • Show All 42 Lines • ▼ Show 20 Lines
	.El			.El
	.Sh RETURN VALUES			.Sh RETURN VALUES
	If successful,			If successful,
	.Fn memfd_create			.Fn memfd_create
	and			and
	.Fn shm_open			.Fn shm_open
	both return a non-negative integer,			both return a non-negative integer,
	and			and
				.Fn shm_rename
				and
	.Fn shm_unlink			.Fn shm_unlink
	returns zero.			return zero.
	All three functions return -1 on failure, and set			All functions return -1 on failure, and set
	.Va errno			.Va errno
	to indicate the error.			to indicate the error.
	.Sh COMPATIBILITY			.Sh COMPATIBILITY
	The			The
	.Fa path			.Fa path ,
	argument does not necessarily represent a pathname (although it does in			.Fa path_from ,
				and
				.Fa path_to
				arguments do not necessarily represent a pathname (although they do in
	most other implementations).			most other implementations).
	Two processes opening the same			Two processes opening the same
	.Fa path			.Fa path
	are guaranteed to access the same shared memory object if and only if			are guaranteed to access the same shared memory object if and only if
	.Fa path			.Fa path
	begins with a slash			begins with a slash
	.Pq Ql \&/			.Pq Ql \&/
	character.			character.
	▲ Show 20 Lines • Show All 104 Lines • ▼ Show 20 Lines
	.Dv O_RDONLY			.Dv O_RDONLY
	was specified while creating an anonymous shared memory object via			was specified while creating an anonymous shared memory object via
	.Dv SHM_ANON .			.Dv SHM_ANON .
	.It Bq Er EFAULT			.It Bq Er EFAULT
	The			The
	.Fa path			.Fa path
	argument points outside the process' allocated address space.			argument points outside the process' allocated address space.
	.It Bq Er ENAMETOOLONG			.It Bq Er ENAMETOOLONG
	The entire pathname exceeded 1023 characters.			The entire pathname exceeds 1023 characters.
	.It Bq Er EINVAL			.It Bq Er EINVAL
	The			The
	.Fa path			.Fa path
	does not begin with a slash			does not begin with a slash
	.Pq Ql \&/			.Pq Ql \&/
	character.			character.
	.It Bq Er ENOENT			.It Bq Er ENOENT
	.Dv O_CREAT			.Dv O_CREAT
	is specified and the named shared memory object does not exist.			is specified and the named shared memory object does not exist.
	.It Bq Er EEXIST			.It Bq Er EEXIST
	.Dv O_CREAT			.Dv O_CREAT
	and			and
	.Dv O_EXCL			.Dv O_EXCL
	are specified and the named shared memory object does exist.			are specified and the named shared memory object does exist.
	.It Bq Er EACCES			.It Bq Er EACCES
	The required permissions (for reading or reading and writing) are denied.			The required permissions (for reading or reading and writing) are denied.
	.El			.El
	.Pp			.Pp
				The following errors are defined for
				.Fn shm_rename :
				.Bl -tag -width Er
				.It Bq Er EFAULT
				The
				.Fa path_from
				or
				.Fa path_to
				argument points outside the process' allocated address space.
				.It Bq Er ENAMETOOLONG
				The entire pathname exceeds 1023 characters.
				.It Bq Er ENOENT
				The shared memory object at
				.Fa path_from
				does not exist.
				.It Bq Er EACCES
				The required permissions are denied.
				.It Bq Er EEXIST
				An shm exists at
				.Fa path_to ,
				and the
				.Dv SHM_RENAME_NOREPLACE
				flag was provided.
				.El
				.Pp
	.Fn shm_unlink			.Fn shm_unlink
	fails with these error codes for these conditions:			fails with these error codes for these conditions:
	.Bl -tag -width Er			.Bl -tag -width Er
	.It Bq Er EFAULT			.It Bq Er EFAULT
	The			The
	.Fa path			.Fa path
	argument points outside the process' allocated address space.			argument points outside the process' allocated address space.
	.It Bq Er ENAMETOOLONG			.It Bq Er ENAMETOOLONG
	The entire pathname exceeded 1023 characters.			The entire pathname exceeds 1023 characters.
	.It Bq Er ENOENT			.It Bq Er ENOENT
	The named shared memory object does not exist.			The named shared memory object does not exist.
	.It Bq Er EACCES			.It Bq Er EACCES
	The required permissions are denied.			The required permissions are denied.
	.Fn shm_unlink			.Fn shm_unlink
	requires write permission to the shared memory object.			requires write permission to the shared memory object.
	.El			.El
	.Sh SEE ALSO			.Sh SEE ALSO
	Show All 25 Lines
	.Fn shm_open			.Fn shm_open
	and			and
	.Fn shm_unlink			.Fn shm_unlink
	functions first appeared in			functions first appeared in
	.Fx 4.3 .			.Fx 4.3 .
	The functions were reimplemented as system calls using shared memory objects			The functions were reimplemented as system calls using shared memory objects
	directly rather than files in			directly rather than files in
	.Fx 8.0 .			.Fx 8.0 .
				.Pp
				.Fn shm_rename
				first appeared in
				.Fx 13.0
				as a
				.Fx
				extension.
	.Sh AUTHORS			.Sh AUTHORS
	.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org			.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
	(C library support and this manual page)			(C library support and this manual page)
	.Pp			.Pp
	.An Matthew Dillon Aq Mt dillon@FreeBSD.org			.An Matthew Dillon Aq Mt dillon@FreeBSD.org
	.Pq Dv MAP_NOSYNC			.Pq Dv MAP_NOSYNC
				.Pp
				.An Matthew Bryan Aq Mt matthew.bryan@isilon.com
				.Pq Dv shm_rename implementation