Add shm_open(3) and shm_unlink(3). The documentation could use a good

bit of work (and is stylistically probably the worst manual page
I've ever written).

1 files changed, 192 insertions, 0 deletions

diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2
new file mode 100644
index 0000000..0bb54e6
--- /dev/null
+++ b/lib/libc/sys/shm_open.2
@@ -0,0 +1,192 @@
+.\"
+.\" Copyright 2000 Massachusetts Institute of Technology
+.\"
+.\" Permission to use, copy, modify, and distribute this software and
+.\" its documentation for any purpose and without fee is hereby
+.\" granted, provided that both the above copyright notice and this
+.\" permission notice appear in all copies, that both the above
+.\" copyright notice and this permission notice appear in all
+.\" supporting documentation, and that the name of M.I.T. not be used
+.\" in advertising or publicity pertaining to distribution of the
+.\" software without specific, written prior permission.  M.I.T. makes
+.\" no representations about the suitability of this software for any
+.\" purpose.  It is provided "as is" without express or implied
+.\" warranty.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
+.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
+.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd March 24, 2000
+.Dt SHM_OPEN 3
+.Os
+.Sh NAME
+.Nm shm_open
+.Nd open or create a shared memory object
+.Nm shm_unlink
+.Nd remove a shared memory object
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
+.Ft int
+.Fn shm_open "const char *path" "int flags" "mode_t mode"
+.Ft int
+.Fn shm_unlink "const char *path"
+.Sh DESCRIPTION
+The
+.Nm shm_open
+function opens (or optionally creates) a
+.Tn POSIX
+shared memory object named
+.Fa path .
+The
+.Nm 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
+.Nm shm_open
+and
+.Nm shm_unlink
+act as wrappers around the
+.Xr open 2
+and
+.Xr unlink 2
+routines, and
+.Fa path ,
+.Fa flags ,
+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).
+.Pp
+In addition, the
+.Fx
+implementation causes
+.Fn mmap
+of a descriptor returned by
+.Nm shm_open
+to behave as if the
+.Dv MAP_ASYNC
+flag had been specified to
+.Xr mmap 2 .
+(It does so by setting a special file flag using
+.Xr fcntl 2 . )
+.Pp
+The
+.Nm shm_unlink
+function makes no effort to ensure that
+.Fa path
+refers to a shared memory object.
+.Sh PORTABILITY
+The
+.Fa path
+argument does not necessarily represent a pathname (although it does in this
+and most other implementations).
+Two processes opening the same
+.Fa path
+are guaranteed to access the same shared memory object if and only if
+.Fa path
+begins with a slash
+.Pq Ql \&/
+character.
+.Pp
+Only the
+.Dv O_RDONLY ,
+.Dv O_RDWR ,
+.Dv O_CREAT ,
+.Dv O_EXCL ,
+and
+.Dv O_TRUNC
+flags may be used in portable programs.
+.Pp
+The result of using
+.Xr open 2 ,
+.Xr read 2 ,
+or
+.Xr write 2
+on a shared memory object, or on the descriptor returned by
+.Fn shm_open ,
+is undefined.
+It is also undefined whether the shared memory object itself, or its 
+contents, persist across reboots.
+.Sh RETURN VALUES
+If successful,
+.Fn shm_open
+returns a non-negative integer;
+.Fn shm_unlink
+returns zero.
+Both functions return -1 on failure, and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn shm_open
+and
+.Fn shm_unlink
+functions can fail with any error defined for
+.Fn open
+and
+.Fn unlink ,
+respectively.  In addition, the following errors are defined for
+.Fn shm_open :
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The object named by
+.Fa path
+is not a shared memory object
+(i.e., it is not a regular file).
+.It Bq Er EINVAL
+The
+.Fa flags
+argument to
+.Fn shm_open
+specifies an access mode of
+.Dv O_WRONLY .
+.El
+.Sh SEE ALSO
+.Xr mmap 2 ,
+.Xr munmap 2 ,
+.Xr open 2 ,
+.Xr unlink 2
+.Sh STANDARDS
+The
+.Nm shm_open
+and
+.Nm shm_unlink
+functions are believed to conform to
+.St -p1003.1b .
+.Sh HISTORY
+The
+.Nm shm_open
+and
+.Nm shm_unlink
+functions first appeared in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Garrett A. Wollman Aq wollman@FreeBSD.org
+(C library support and this manual page)
+.Pp
+.An Matthew Dillon Aq dillon@FreeBSD.org
+.Pq Dv MAP_NOSYNC
+