1.\" 2.\" Copyright 2000 Massachusetts Institute of Technology 3.\" 4.\" Permission to use, copy, modify, and distribute this software and 5.\" its documentation for any purpose and without fee is hereby 6.\" granted, provided that both the above copyright notice and this 7.\" permission notice appear in all copies, that both the above 8.\" copyright notice and this permission notice appear in all 9.\" supporting documentation, and that the name of M.I.T. not be used 10.\" in advertising or publicity pertaining to distribution of the 11.\" software without specific, written prior permission. M.I.T. makes 12.\" no representations about the suitability of this software for any 13.\" purpose. It is provided "as is" without express or implied 14.\" warranty. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS 17.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, 18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 20.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 21.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 22.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 23.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 26.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD: src/lib/libc/gen/shm_open.3,v 1.3.2.5 2001/12/14 18:33:51 ru Exp $ 30.\" 31.Dd June 28, 2019 32.Dt SHM_OPEN 3 33.Os 34.Sh NAME 35.Nm shm_open , 36.Nm shm_unlink 37.Nd POSIX shared memory object operations 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/types.h 42.In sys/mman.h 43.Ft int 44.Fn shm_open "const char *path" "int flags" "mode_t mode" 45.Ft int 46.Fn shm_unlink "const char *path" 47.Sh DESCRIPTION 48The 49.Fn shm_open 50function opens (or optionally creates) a 51.Tn POSIX 52shared memory object named 53.Fa path . 54The 55.Fn shm_unlink 56function removes a shared memory object named 57.Fa path . 58Using the same 59.Fa path 60allows unrelated processes to access the same object. 61.Sh IMPLEMENTATION NOTES 62.Dx 63mounts a 64.Xr tmpfs 5 65file system at 66.Pa /var/run/shm . 67.Tn POSIX 68shared memory objects are implemented as ordinary files under 69that directory. 70The 71.Fn shm_open 72and 73.Fn shm_unlink 74functions act as wrappers around 75.Xr open 2 76and 77.Xr unlink 2 . 78Any leading slash 79.Pq Ql \&/ 80characters are removed from 81.Fa path 82to make it relative to 83.Pa /var/run/shm . 84The 85.Fa flags 86and 87.Fa mode 88arguments are passed through unaltered. 89.Fa flags 90is checked to ensure that the access mode specified is not 91.Dv O_WRONLY 92(which is not defined for shared memory objects). 93.Pp 94In addition, the 95.Dx 96implementation causes 97.Fn mmap 98of a descriptor returned by 99.Fn shm_open 100to behave as if the 101.Dv MAP_NOSYNC 102flag had been specified to 103.Xr mmap 2 . 104(It does so by setting a special file flag using 105.Xr fcntl 2 . ) 106.Sh RETURN VALUES 107If successful, 108.Fn shm_open 109returns a non-negative integer; 110.Fn shm_unlink 111returns zero. 112Both functions return -1 on failure, and set 113.Va errno 114to indicate the error. 115.Sh COMPATIBILITY 116On 117.Dx 118and many other operating systems the 119.Fa path 120argument is interpreted as a file system pathname under a special 121directory where a memory-backed file system is mounted. 122Most operating systems do some name mangling to 123.Fa path . 124Leading slashes are commonly removed to turn an absolute pathname into 125a relative one. 126Problematic characters may be escaped and there may be a length limit on 127.Fa path . 128On some systems the mangled pathname is completely different from the 129given 130.Fa path . 131On a few systems, shared memory objects live outside the ordinary file 132system in their own dedicated namespace. 133.Pp 134According to 135.Tn POSIX 136two processes opening the same 137.Fa path 138are guaranteed to access the same shared memory object if and only if 139.Fa path 140begins with a slash. 141The most portable form of pathname is probably 142.Ql /foobar , 143i.e.\& one leading slash, no other slashes and no dots. 144.Pp 145The result of using 146.Xr open 2 147on the pathname of a shared memory object, 148or using 149.Xr read 2 150or 151.Xr write 2 152on a file descriptor returned by 153.Fn shm_open , 154is undefined by 155.Tn POSIX . 156It is also undefined whether the shared memory object itself, or its 157contents, persist across reboots. 158On 159.Dx 160and most other systems they do not. 161Only the 162.Dv O_RDONLY , 163.Dv O_RDWR , 164.Dv O_CREAT , 165.Dv O_EXCL , 166and 167.Dv O_TRUNC 168flags may be used in portable programs. 169.Sh ERRORS 170The 171.Fn shm_open 172and 173.Fn shm_unlink 174functions can fail with any error defined for 175.Fn open 176and 177.Fn unlink , 178respectively. 179In addition, the following errors are defined for 180.Fn shm_open : 181.Bl -tag -width Er 182.It Bq Er EINVAL 183The object named by 184.Fa path 185is not a shared memory object 186(i.e., it is not a regular file). 187.It Bq Er EINVAL 188The 189.Fa flags 190argument to 191.Fn shm_open 192specifies an access mode of 193.Dv O_WRONLY . 194.El 195.Sh SEE ALSO 196.Xr mmap 2 , 197.Xr munmap 2 , 198.Xr open 2 , 199.Xr unlink 2 , 200.Xr tmpfs 5 201.Sh STANDARDS 202The 203.Fn shm_open 204and 205.Fn shm_unlink 206functions are believed to conform to 207.St -p1003.1b-93 . 208.Sh HISTORY 209The 210.Fn shm_open 211and 212.Fn shm_unlink 213functions first appeared in 214.Fx 4.3 . 215.Sh AUTHORS 216.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org 217(C library support and this manual page) 218.An Matthew Dillon Aq Mt dillon@FreeBSD.org 219.Pq Dv MAP_NOSYNC 220