Add a new file descriptor type for IPC shared memory objects and use it to

implement shm_open(2) and shm_unlink(2) in the kernel:
- Each shared memory file descriptor is associated with a swap-backed vm
  object which provides the backing store.  Each descriptor starts off with
  a size of zero, but the size can be altered via ftruncate(2).  The shared
  memory file descriptors also support fstat(2).  read(2), write(2),
  ioctl(2), select(2), poll(2), and kevent(2) are not supported on shared
  memory file descriptors.
- shm_open(2) and shm_unlink(2) are now implemented as system calls that
  manage shared memory file descriptors.  The virtual namespace that maps
  pathnames to shared memory file descriptors is implemented as a hash
  table where the hash key is generated via the 32-bit Fowler/Noll/Vo hash
  of the pathname.
- As an extension, the constant 'SHM_ANON' may be specified in place of the
  path argument to shm_open(2).  In this case, an unnamed shared memory
  file descriptor will be created similar to the IPC_PRIVATE key for
  shmget(2).  Note that the shared memory object can still be shared among
  processes by sharing the file descriptor via fork(2) or sendmsg(2), but
  it is unnamed.  This effectively serves to implement the getmemfd() idea
  bandied about the lists several times over the years.
- The backing store for shared memory file descriptors are garbage
  collected when they are not referenced by any open file descriptors or
  the shm_open(2) virtual namespace.

Submitted by:	dillon, peter (previous versions)
Submitted by:	rwatson (I based this on his version)
Reviewed by:	alc (suggested converting getmemfd() to shm_open())

1 files changed, 157 insertions, 67 deletions

diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2
index b68e85b..5c5d694 100644
--- a/lib/libc/sys/shm_open.2
+++ b/lib/libc/sys/shm_open.2
@@ -28,8 +28,8 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 24, 2000
-.Dt SHM_OPEN 3
+.Dd March 20, 2007
+.Dt SHM_OPEN 2
 .Os
 .Sh NAME
 .Nm shm_open , shm_unlink
@@ -46,62 +46,104 @@
 .Sh DESCRIPTION
 The
 .Fn shm_open
-function opens (or optionally creates) a
+system call opens (or optionally creates) a
 .Tn POSIX
 shared memory object named
 .Fa path .
 The
-.Fn shm_unlink
-function removes a shared memory object named
-.Fa path .
-.Pp
-In the
-.Fx
-implementation,
-.Tn POSIX
-shared memory objects are implemented as ordinary files.
-The
-.Fn shm_open
+.Fa flags
+argument contains a subset of the flags used by
+.Xr open 2 .
+An access mode of either
+.Dv O_RDONLY
+or
+.Dv O_RDWR
+must be included in
+.Fa flags .
+The optional flags
+.Dv O_CREAT ,
+.Dv O_EXCL ,
 and
-.Fn shm_unlink
-act as wrappers around the
-.Xr open 2
+.Dv O_TRUNC
+may also be specified.
+.Pp
+If
+.Dv O_CREAT
+is specified,
+then a new shared memory object named
+.Fa path
+will be created if it does not exist.
+In this case,
+the shared memory object is created with mode
+.Fa mode
+subject to the process' umask value.
+If both the
+.Dv O_CREAT
 and
-.Xr unlink 2
-routines, and
-.Fa path ,
-.Fa flags ,
+.Dv O_EXCL
+flags are specified and a shared memory object named
+.Fa path
+already exists,
+then
+.Fn shm_open
+will fail with
+.Er EEXIST.
+.Pp
+Newly created objects start off with a size of zero.
+If an existing shared memory object is opened with
+.Dv O_RDWR
+and the
+.Dv O_TRUNC
+flag is specified,
+then the shared memory object will be truncated to a size of zero.
+The size of the object can be adjusted via
+.Xr ftruncate 2
+and queried via
+.Xr fstat 2 .
+.Pp
+The new descriptor is set to close during
+.Xr execve 2
+system calls;
+see
+.Xr close 2
 and
-.Fa mode
-arguments are as specified for those functions.
-The
-.Fa flags
-argument is checked to ensure that the access mode specified is not
-.Dv O_WRONLY
-(which is not defined for shared memory objects).
+.Xr fcntl 2 .
 .Pp
-In addition, the
-.Fx
-implementation causes
-.Fn mmap
-of a descriptor returned by
-.Fn shm_open
-to behave as if the
-.Dv MAP_NOSYNC
-flag had been specified to
-.Xr mmap 2 .
-(It does so by setting a special file flag using
-.Xr fcntl 2 . )
+As a FreeBSD extension,
+the constant
+.Dv SHM_ANON
+may be used for the
+.Fa path
+argument to
+.Fn shm_open .
+In this case, an anonymous, unnamed shared memory object is created.
+Since the object has no name,
+it cannot be removed via a subsequent call to
+.Fn shm_unlink .
+Instead,
+the shared memory object will be garbage collected when the last reference to
+the shared memory object is removed.
+The shared memory object may be shared with other processes by sharing the
+file descriptor via
+.Xr fork 2
+or
+.Xr sendmsg 2 .
+Attempting to open an anonymous shared memory object with
+.Dv O_RDONLY
+will fail with
+.Er EINVAL .
+All other flags are ignored.
 .Pp
 The
 .Fn shm_unlink
-function makes no effort to ensure that
-.Fa path
-refers to a shared memory object.
+system call removes a shared memory object named
+.Fa path .
+.Pp
 .Sh RETURN VALUES
 If successful,
 .Fn shm_open
-returns a non-negative integer;
+returns a non-negative integer,
+and
 .Fn shm_unlink
 returns zero.
 Both functions return -1 on failure, and set
@@ -110,8 +152,8 @@ to indicate the error.
 .Sh COMPATIBILITY
 The
 .Fa path
-argument does not necessarily represent a pathname (although it does in this
-and most other implementations).
+argument does not necessarily represent a pathname (although it does in
+most other implementations).
 Two processes opening the same
 .Fa path
 are guaranteed to access the same shared memory object if and only if
@@ -139,37 +181,82 @@ on a shared memory object, or on the descriptor returned by
 is undefined.
 It is also undefined whether the shared memory object itself, or its
 contents, persist across reboots.
-.Sh ERRORS
-The
-.Fn shm_open
-and
-.Fn shm_unlink
-functions can fail with any error defined for
-.Fn open
+.Pp
+In FreeBSD,
+.Xr read 2
 and
-.Fn unlink ,
-respectively.
-In addition, the following errors are defined for
+.Xr write 2
+on a shared memory object will fail with
+.Er EOPNOTSUPP
+and neither shared memory objects nor their contents persist across reboots.
+.Sh ERRORS
+The following errors are defined for
 .Fn shm_open :
 .Bl -tag -width Er
 .It Bq Er EINVAL
-The object named by
+A flag other than
+.Dv O_RDONLY ,
+.Dv O_RDWR ,
+.Dv O_CREAT ,
+.Dv O_EXCL ,
+or
+.Dv O_TRUNC
+was included in
+.Fa flags .
+.It Bq Er EMFILE
+The process has already reached its limit for open file descriptors.
+.It Bq Er ENFILE
+The system file table is full.
+.It Bq Er EINVAL
+.Dv O_RDONLY
+was specified while creating an anonymous shared memory object via
+.Dv SHM_ANON .
+.It Bq Er EFAULT
+The
 .Fa path
-is not a shared memory object
-(i.e., it is not a regular file).
+argument points outside the process' allocated address space.
+.It Bq Er ENAMETOOLONG
+The entire pathname exceeded 1023 characters.
 .It Bq Er EINVAL
 The
-.Fa flags
-argument to
-.Fn shm_open
-specifies an access mode of
-.Dv O_WRONLY .
+.Fa path
+does not begin with a slash
+.Pq Ql \&/
+character.
+.It Bq Er ENOENT
+.Dv O_CREAT
+is specified and the named shared memory object does not exist.
+.It Bq Er EEXIST
+.Dv O_CREAT
+and
+.Dv O_EXCL
+are specified and the named shared memory object dies exist.
+.It Bq Er EACCES
+The required permissions (for reading or reading and writing) are denied.
+.El
+.Pp
+The following errors are defined for
+.Fn shm_unlink :
+.Bl -tag -width Er
+.It Bq Er EFAULT
+The
+.Fa path
+argument points outside the process' allocated address space.
+.It Bq Er ENAMETOOLONG
+The entire pathname exceeded 1023 characters.
+.It Bq Er ENOENT
+The named shared memory object does not exist.
+.It Bq Er EACCES
+The required permissions are denied.
+.Fn shm_unlink
+requires write permission to the shared memory object.
 .El
 .Sh SEE ALSO
+.Xr close 2 ,
+.Xr ftruncate 2 ,
+.Xr fstat 2 ,
 .Xr mmap 2 ,
-.Xr munmap 2 ,
-.Xr open 2 ,
-.Xr unlink 2
+.Xr munmap 2
 .Sh STANDARDS
 The
 .Fn shm_open
@@ -184,6 +271,9 @@ and
 .Fn shm_unlink
 functions first appeared in
 .Fx 4.3 .
+The functions were reimplemented as system calls using shared memory objects
+directly rather than files in
+.Fx 7.0 .
 .Sh AUTHORS
 .An Garrett A. Wollman Aq wollman@FreeBSD.org
 (C library support and this manual page)