From 733719bd9e10a6d1282245960209fcd8840ccae8 Mon Sep 17 00:00:00 2001
From: Matthew Dillon <dillon@apollo.backplane.com>
Date: Fri, 28 Jun 2019 09:22:39 -0700
Subject: [PATCH] docs - Update shm_open(3) manual page

* Update to detail recent work.

Submitted-by: Lassi Kortela
---
 lib/libc/gen/shm_open.3 | 100 ++++++++++++++++++++++++++++++------------------
 1 file changed, 62 insertions(+), 38 deletions(-)

diff --git a/lib/libc/gen/shm_open.3 b/lib/libc/gen/shm_open.3
index dc0f350546..4ddc8460d7 100644
--- a/lib/libc/gen/shm_open.3
+++ b/lib/libc/gen/shm_open.3
@@ -34,7 +34,7 @@
 .Sh NAME
 .Nm shm_open ,
 .Nm shm_unlink
-.Nd shared memory object operations
+.Nd POSIX shared memory object operations
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -55,29 +55,39 @@ The
 .Fn shm_unlink
 function removes a shared memory object named
 .Fa path .
+Using the same
+.Fa path
+allows unrelated processes to access the same object.
 .Pp
-In the
 .Dx
-implementation,
+mounts a
+.Xr tmpfs 5
+file system at
+.Pa /var/run/shm .
 .Tn POSIX
-shared memory objects are implemented as ordinary files.
+shared memory objects are implemented as ordinary files under
+that directory.
 The
 .Fn shm_open
 and
 .Fn shm_unlink
-act as wrappers around the
+functions act as wrappers around
 .Xr open 2
 and
-.Xr unlink 2
-routines, and
-.Fa path ,
-.Fa flags ,
+.Xr unlink 2 .
+Any leading slash
+.Pq Ql \&/
+characters are removed from
+.Fa path
+to make it relative to
+.Pa /var/run/shm .
+The
+.Fa flags
 and
 .Fa mode
-arguments are as specified for those functions.
-The
+arguments are passed through unaltered.
 .Fa flags
-argument is checked to ensure that the access mode specified is not
+is checked to ensure that the access mode specified is not
 .Dv O_WRONLY
 (which is not defined for shared memory objects).
 .Pp
@@ -93,12 +103,6 @@ flag had been specified to
 .Xr mmap 2 .
 (It does so by setting a special file flag using
 .Xr fcntl 2 . )
-.Pp
-The
-.Fn shm_unlink
-function makes no effort to ensure that
-.Fa path
-refers to a shared memory object.
 .Sh RETURN VALUES
 If successful,
 .Fn shm_open
@@ -109,19 +113,49 @@ Both functions return -1 on failure, and set
 .Va errno
 to indicate the error.
 .Sh COMPATIBILITY
-The
+On
+.Dx
+and many other operating systems the
 .Fa path
-argument does not necessarily represent a pathname (although it does in this
-and most other implementations).
-Two processes opening the same
+argument is interpreted as a file system pathname under a special
+directory where a memory-backed file system is mounted.  Most
+operating systems do some name mangling to
+.Fa path .
+Leading slashes are commonly removed to turn an absolute pathname into
+a relative one.  Problematic characters may be escaped and there may
+be a length limit on
+.Fa path .
+On some systems the mangled pathname is completely different from the
+given
+.Fa path .
+On a few systems, shared memory objects live outside the ordinary file
+system in their own dedicated namespace.
+.Pp
+According to
+.Tn POSIX
+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.
+begins with a slash. The most portable form of pathname is probably
+.Ql /foobar ,
+i.e. one leading slash, no other slashes and no dots.
 .Pp
-Only the
+The result of using
+.Xr open 2
+on the pathname of a shared memory object,
+or using
+.Xr read 2
+or
+.Xr write 2
+on a file descriptor returned by
+.Fn shm_open ,
+is undefined by
+.Tn POSIX .
+It is also undefined whether the shared memory object itself, or its
+contents, persist across reboots.  On
+.Dx
+and most other systems they do not.  Only the
 .Dv O_RDONLY ,
 .Dv O_RDWR ,
 .Dv O_CREAT ,
@@ -129,17 +163,6 @@ Only the
 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
 .Fn shm_open
@@ -169,7 +192,8 @@ specifies an access mode of
 .Xr mmap 2 ,
 .Xr munmap 2 ,
 .Xr open 2 ,
-.Xr unlink 2
+.Xr unlink 2 ,
+.Xr tmpfs 5
 .Sh STANDARDS
 The
 .Fn shm_open
-- 
2.11.4.GIT