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)