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$ 30.\" 31.Dd March 20, 2007 32.Dt SHM_OPEN 2 33.Os 34.Sh NAME 35.Nm shm_open , shm_unlink 36.Nd "shared memory object operations" 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/mman.h 42.In fcntl.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 50system call opens (or optionally creates) a 51.Tn POSIX 52shared memory object named 53.Fa path . 54The 55.Fa flags 56argument contains a subset of the flags used by 57.Xr open 2 . 58An access mode of either 59.Dv O_RDONLY 60or 61.Dv O_RDWR 62must be included in 63.Fa flags . 64The optional flags 65.Dv O_CREAT , 66.Dv O_EXCL , 67and 68.Dv O_TRUNC 69may also be specified. 70.Pp 71If 72.Dv O_CREAT 73is specified, 74then a new shared memory object named 75.Fa path 76will be created if it does not exist. 77In this case, 78the shared memory object is created with mode 79.Fa mode 80subject to the process' umask value. 81If both the 82.Dv O_CREAT 83and 84.Dv O_EXCL 85flags are specified and a shared memory object named 86.Fa path 87already exists, 88then 89.Fn shm_open 90will fail with 91.Er EEXIST . 92.Pp 93Newly created objects start off with a size of zero. 94If an existing shared memory object is opened with 95.Dv O_RDWR 96and the 97.Dv O_TRUNC 98flag is specified, 99then the shared memory object will be truncated to a size of zero. 100The size of the object can be adjusted via 101.Xr ftruncate 2 102and queried via 103.Xr fstat 2 . 104.Pp 105The new descriptor is set to close during 106.Xr execve 2 107system calls; 108see 109.Xr close 2 110and 111.Xr fcntl 2 . 112.Pp 113As a FreeBSD extension, 114the constant 115.Dv SHM_ANON 116may be used for the 117.Fa path 118argument to 119.Fn shm_open . 120In this case, an anonymous, unnamed shared memory object is created. 121Since the object has no name, 122it cannot be removed via a subsequent call to 123.Fn shm_unlink . 124Instead, 125the shared memory object will be garbage collected when the last reference to 126the shared memory object is removed. 127The shared memory object may be shared with other processes by sharing the 128file descriptor via 129.Xr fork 2 130or 131.Xr sendmsg 2 . 132Attempting to open an anonymous shared memory object with 133.Dv O_RDONLY 134will fail with 135.Er EINVAL . 136All other flags are ignored. 137.Pp 138The 139.Fn shm_unlink 140system call removes a shared memory object named 141.Fa path . 142.Sh RETURN VALUES 143If successful, 144.Fn shm_open 145returns a non-negative integer, 146and 147.Fn shm_unlink 148returns zero. 149Both functions return -1 on failure, and set 150.Va errno 151to indicate the error. 152.Sh COMPATIBILITY 153The 154.Fa path 155argument does not necessarily represent a pathname (although it does in 156most other implementations). 157Two processes opening the same 158.Fa path 159are guaranteed to access the same shared memory object if and only if 160.Fa path 161begins with a slash 162.Pq Ql \&/ 163character. 164.Pp 165Only the 166.Dv O_RDONLY , 167.Dv O_RDWR , 168.Dv O_CREAT , 169.Dv O_EXCL , 170and 171.Dv O_TRUNC 172flags may be used in portable programs. 173.Pp 174The result of using 175.Xr open 2 , 176.Xr read 2 , 177or 178.Xr write 2 179on a shared memory object, or on the descriptor returned by 180.Fn shm_open , 181is undefined. 182It is also undefined whether the shared memory object itself, or its 183contents, persist across reboots. 184.Pp 185In FreeBSD, 186.Xr read 2 187and 188.Xr write 2 189on a shared memory object will fail with 190.Er EOPNOTSUPP 191and neither shared memory objects nor their contents persist across reboots. 192.Sh ERRORS 193The following errors are defined for 194.Fn shm_open : 195.Bl -tag -width Er 196.It Bq Er EINVAL 197A flag other than 198.Dv O_RDONLY , 199.Dv O_RDWR , 200.Dv O_CREAT , 201.Dv O_EXCL , 202or 203.Dv O_TRUNC 204was included in 205.Fa flags . 206.It Bq Er EMFILE 207The process has already reached its limit for open file descriptors. 208.It Bq Er ENFILE 209The system file table is full. 210.It Bq Er EINVAL 211.Dv O_RDONLY 212was specified while creating an anonymous shared memory object via 213.Dv SHM_ANON . 214.It Bq Er EFAULT 215The 216.Fa path 217argument points outside the process' allocated address space. 218.It Bq Er ENAMETOOLONG 219The entire pathname exceeded 1023 characters. 220.It Bq Er EINVAL 221The 222.Fa path 223does not begin with a slash 224.Pq Ql \&/ 225character. 226.It Bq Er ENOENT 227.Dv O_CREAT 228is specified and the named shared memory object does not exist. 229.It Bq Er EEXIST 230.Dv O_CREAT 231and 232.Dv O_EXCL 233are specified and the named shared memory object does exist. 234.It Bq Er EACCES 235The required permissions (for reading or reading and writing) are denied. 236.El 237.Pp 238The following errors are defined for 239.Fn shm_unlink : 240.Bl -tag -width Er 241.It Bq Er EFAULT 242The 243.Fa path 244argument points outside the process' allocated address space. 245.It Bq Er ENAMETOOLONG 246The entire pathname exceeded 1023 characters. 247.It Bq Er ENOENT 248The named shared memory object does not exist. 249.It Bq Er EACCES 250The required permissions are denied. 251.Fn shm_unlink 252requires write permission to the shared memory object. 253.El 254.Sh SEE ALSO 255.Xr close 2 , 256.Xr ftruncate 2 , 257.Xr fstat 2 , 258.Xr mmap 2 , 259.Xr munmap 2 260.Sh STANDARDS 261The 262.Fn shm_open 263and 264.Fn shm_unlink 265functions are believed to conform to 266.St -p1003.1b-93 . 267.Sh HISTORY 268The 269.Fn shm_open 270and 271.Fn shm_unlink 272functions first appeared in 273.Fx 4.3 . 274The functions were reimplemented as system calls using shared memory objects 275directly rather than files in 276.Fx 7.0 . 277.Sh AUTHORS 278.An Garrett A. Wollman Aq wollman@FreeBSD.org 279(C library support and this manual page) 280.Pp 281.An Matthew Dillon Aq dillon@FreeBSD.org 282.Pq Dv MAP_NOSYNC 283