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).

4 files changed, 457 insertions, 2 deletions

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index 2722265..6a766b3 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -19,6 +19,7 @@ SRCS+=  _rand48.c _spinlock_stub.c alarm.c arc4random.c assert.c \
 	msgget.c msgrcv.c msgsnd.c nice.c \
 	nlist.c nrand48.c ntp_gettime.c opendir.c \
 	pause.c popen.c psignal.c pwcache.c raise.c readdir.c rewinddir.c \
+	posixshm.c \
 	scandir.c seed48.c seekdir.c semconfig.c semctl.c semget.c semop.c \
 	setdomainname.c sethostname.c setjmperr.c setmode.c shmat.c \
 	shmctl.c shmdt.c shmget.c siginterrupt.c siglist.c signal.c \
@@ -45,8 +46,8 @@ MAN3+=  alarm.3 arc4random.3 clock.3 \
 	glob.3 initgroups.3 isinf.3 \
 	ldexp.3 lockf.3 modf.3 msgctl.3 msgget.3 msgrcv.3 msgsnd.3 \
 	nice.3 nlist.3 pause.3 popen.3 psignal.3 pwcache.3 \
-	raise.3 rand48.3 scandir.3 setjmp.3 setmode.3 siginterrupt.3 \
-	signal.3 sigsetops.3 sleep.3 stringlist.3 \
+	raise.3 rand48.3 scandir.3 setjmp.3 setmode.3 shm_open.3 \
+	siginterrupt.3 signal.3 sigsetops.3 sleep.3 stringlist.3 \
 	sysconf.3 sysctl.3 syslog.3 tcgetpgrp.3 \
 	tcsendbreak.3 tcsetattr.3 tcsetpgrp.3 time.3 times.3 timezone.3 \
 	ttyname.3 tzset.3 ualarm.3 uname.3 unvis.3 usleep.3 utime.3 \
@@ -104,6 +105,7 @@ MLINKS+=setjmp.3 _longjmp.3 setjmp.3 _setjmp.3 setjmp.3 longjmp.3 \
 	setjmp.3 longjmperr.3 setjmp.3 longjmperror.3 \
 	setjmp.3 siglongjmp.3 setjmp.3 sigsetjmp.3
 MLINKS+=setmode.3 getmode.3
+MLINKS+=shm_open.3 shm_unlink.3
 MLINKS+=sigsetops.3 sigaddset.3 sigsetops.3 sigdelset.3 \
 	sigsetops.3 sigemptyset.3 sigsetops.3 sigfillset.3 \
 	sigsetops.3 sigismember.3
diff --git a/lib/libc/gen/posixshm.c b/lib/libc/gen/posixshm.c
new file mode 100644
index 0000000..78429cf
--- /dev/null
+++ b/lib/libc/gen/posixshm.c
@@ -0,0 +1,69 @@
+/*
+ * 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$
+ */
+
+#include <sys/types.h>
+#include <sys/fcntl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+
+#include <errno.h>
+#include <unistd.h>
+
+int
+shm_open(const char *path, int flags, mode_t mode)
+{
+	int fd;
+	struct stat stab;
+
+	if ((flags & O_ACCMODE) == O_WRONLY)
+		return (EINVAL);
+
+	fd = open(path, flags, mode);
+	if (fd != -1) {
+		if (fstat(fd, &stab) != 0 || !S_ISREG(stab.st_mode)) {
+			close(fd);
+			errno = EINVAL;
+			return (-1);
+		}
+
+		if (fcntl(fd, F_SETFL, (int)FPOSIXSHM) != 0) {
+			close(fd);
+			return (-1);
+		}
+	}
+	return (fd);
+}
+
+int
+shm_unlink(const char *path)
+{
+	return (unlink(path));
+}
diff --git a/lib/libc/gen/shm_open.3 b/lib/libc/gen/shm_open.3
new file mode 100644
index 0000000..0bb54e6
--- /dev/null
+++ b/lib/libc/gen/shm_open.3
@@ -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
+
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
+