[src/trunk]: src Add a man page for shm_open(3) and shm_unlink(3). Obtained ...

[rmind <rmind%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/24f94cb6fdde
branches:  trunk
changeset: 792083:24f94cb6fdde
user:      rmind <rmind%NetBSD.org@localhost>
date:      Thu Dec 19 19:40:08 2013 +0000

description:
Add a man page for shm_open(3) and shm_unlink(3).  Obtained from FreeBSD,
with various modifications.

diffstat:

 distrib/sets/lists/comp/mi |    8 +-
 lib/librt/Makefile         |    5 +-
 lib/librt/shm_open.3       |  241 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 251 insertions(+), 3 deletions(-)

diffs (truncated from 307 to 300 lines):

diff -r 57c659735910 -r 24f94cb6fdde distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Thu Dec 19 19:11:50 2013 +0000
+++ b/distrib/sets/lists/comp/mi        Thu Dec 19 19:40:08 2013 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1871 2013/12/18 20:14:02 pooka Exp $
+#      $NetBSD: mi,v 1.1872 2013/12/19 19:40:08 rmind Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -8760,6 +8760,8 @@
 ./usr/share/man/cat3/sha.0                     comp-obsolete           obsolete
 ./usr/share/man/cat3/sha1.0                    comp-c-catman           .cat
 ./usr/share/man/cat3/sha2.0                    comp-c-catman           .cat
+./usr/share/man/cat3/shm_open.0                        comp-c-catman           .cat
+./usr/share/man/cat3/shm_unlink.0              comp-c-catman           .cat
 ./usr/share/man/cat3/shquote.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/shquotev.0                        comp-c-catman           .cat
 ./usr/share/man/cat3/sigaddset.0               comp-c-catman           .cat
@@ -15288,6 +15290,8 @@
 ./usr/share/man/html3/setvbuf.html             comp-c-htmlman          html
 ./usr/share/man/html3/sha1.html                        comp-c-htmlman          html
 ./usr/share/man/html3/sha2.html                        comp-c-htmlman          html
+./usr/share/man/html3/shm_open.html            comp-c-htmlman          html
+./usr/share/man/html3/shm_unlink.html          comp-c-htmlman          html
 ./usr/share/man/html3/shquote.html             comp-c-htmlman          html
 ./usr/share/man/html3/shquotev.html            comp-c-htmlman          html
 ./usr/share/man/html3/sigaddset.html           comp-c-htmlman          html
@@ -21830,6 +21834,8 @@
 ./usr/share/man/man3/sha.3                     comp-obsolete           obsolete
 ./usr/share/man/man3/sha1.3                    comp-c-man              .man
 ./usr/share/man/man3/sha2.3                    comp-c-man              .man
+./usr/share/man/man3/shm_open.3                        comp-c-man              .man
+./usr/share/man/man3/shm_unlink.3              comp-c-man              .man
 ./usr/share/man/man3/shquote.3                 comp-c-man              .man
 ./usr/share/man/man3/shquotev.3                        comp-c-man              .man
 ./usr/share/man/man3/sigaddset.3               comp-c-man              .man
diff -r 57c659735910 -r 24f94cb6fdde lib/librt/Makefile
--- a/lib/librt/Makefile        Thu Dec 19 19:11:50 2013 +0000
+++ b/lib/librt/Makefile        Thu Dec 19 19:40:08 2013 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.17 2013/12/19 19:11:50 rmind Exp $
+#      $NetBSD: Makefile,v 1.18 2013/12/19 19:40:08 rmind Exp $
 #
 
 .include <bsd.own.mk>
@@ -13,7 +13,7 @@
        aio_suspend.3 aio_write.3 lio_listio.3 \
        mq.3 mq_close.3 mq_getattr.3 mq_notify.3 mq_open.3 mq_receive.3 \
        mq_send.3 mq_setattr.3 mq_unlink.3 \
-       pset.3 sched.3 \
+       pset.3 sched.3 shm_open.3 \
        sem_destroy.3 sem_getvalue.3 sem_init.3 sem_open.3 sem_post.3 \
        sem_wait.3
 
@@ -40,6 +40,7 @@
 MLINKS+=       sched.3 sched_rr_get_interval.3
 MLINKS+=       sched.3 sched_yield.3
 
+MLINKS+=       shm_open.3 shm_unlink.3
 
 .include "${.CURDIR}/../libc/libcincludes.mk"
 
diff -r 57c659735910 -r 24f94cb6fdde lib/librt/shm_open.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/librt/shm_open.3      Thu Dec 19 19:40:08 2013 +0000
@@ -0,0 +1,241 @@
+.\" $NetBSD: shm_open.3,v 1.1 2013/12/19 19:40:08 rmind Exp $
+.\"
+.\" 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 December 19, 2013
+.Dt SHM_OPEN 3
+.Os
+.Sh NAME
+.Nm shm_open , shm_unlink
+.Nd "shared memory object operations"
+.Sh LIBRARY
+.Lb librt
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/mman.h
+.In fcntl.h
+.Ft int
+.Fn shm_open "const char *name" "int flags" "mode_t mode"
+.Ft int
+.Fn shm_unlink "const char *name"
+.Sh DESCRIPTION
+The
+.Fn shm_open
+function creates or opens a
+.Tn POSIX
+shared memory object named
+.Fa name .
+The
+.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
+.Dv O_TRUNC
+may also be specified.
+.Pp
+If
+.Dv O_CREAT
+is specified,
+then a new shared memory object named
+.Fa name
+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
+.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
+.Xr fcntl 2 .
+.Pp
+The
+.Fn shm_unlink
+system call removes a shared memory object named
+.Fa path .
+.Sh RETURN VALUES
+If successful,
+.Fn shm_open
+returns a non-negative integer,
+and
+.Fn shm_unlink
+returns zero.
+Both functions return -1 on failure, and set
+.Va errno
+to indicate the error.
+.Sh COMPATIBILITY
+The
+.Fa path
+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
+.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 ERRORS
+The following errors are defined for
+.Fn shm_open :
+.Bl -tag -width Er
+.It Bq Er EINVAL
+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 EFAULT
+The
+.Fa path
+argument points outside the process' allocated address space.
+.It Bq Er ENAMETOOLONG
+The entire pathname exceeded
+.Brq Dv PATH_MAX
+characters.
+.It Bq Er EINVAL
+The
+.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 ENOTSUP
+Not supported, most likely due to missing or incorrect
+.Pa /var/shm
+mount.
+.It Bq Er EEXIST
+.Dv O_CREAT
+and
+.Dv O_EXCL
+are specified and the named shared memory object does 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
+.Brq Dv PATH_MAX
+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 fstat 2 ,
+.Xr ftruncate 2 ,
+.Xr mmap 2 ,
+.Xr munmap 2
+.Sh STANDARDS
+The
+.Fn shm_open