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 January 20, 2017 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 174.Tn POSIX 175specifications state that the result of using 176.Xr open 2 , 177.Xr read 2 , 178or 179.Xr write 2 180on a shared memory object, or on the descriptor returned by 181.Fn shm_open , 182is undefined. 183However, the 184.Fx 185kernel implementation explicitly includes support for 186.Xr read 2 187and 188.Xr write 2 . 189.Pp 190.Fx 191also supports zero-copy transmission of data from shared memory 192objects with 193.Xr sendfile 2 . 194.Pp 195Neither shared memory objects nor their contents persist across reboots. 196.Pp 197Writes do not extend shared memory objects, so 198.Xr ftruncate 2 199must be called before any data can be written. 200See 201.Sx EXAMPLES . 202.Sh EXAMPLES 203This example fails without the call to 204.Xr ftruncate 2 : 205.Bd -literal -compact 206 207 uint8_t buffer[getpagesize()]; 208 ssize_t len; 209 int fd; 210 211 fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); 212 if (fd < 0) 213 err(EX_OSERR, "%s: shm_open", __func__); 214 if (ftruncate(fd, getpagesize()) < 0) 215 err(EX_IOERR, "%s: ftruncate", __func__); 216 len = pwrite(fd, buffer, getpagesize(), 0); 217 if (len < 0) 218 err(EX_IOERR, "%s: pwrite", __func__); 219 if (len != getpagesize()) 220 errx(EX_IOERR, "%s: pwrite length mismatch", __func__); 221.Ed 222.Sh ERRORS 223.Fn shm_open 224fails with these error codes for these conditions: 225.Bl -tag -width Er 226.It Bq Er EINVAL 227A flag other than 228.Dv O_RDONLY , 229.Dv O_RDWR , 230.Dv O_CREAT , 231.Dv O_EXCL , 232or 233.Dv O_TRUNC 234was included in 235.Fa flags . 236.It Bq Er EMFILE 237The process has already reached its limit for open file descriptors. 238.It Bq Er ENFILE 239The system file table is full. 240.It Bq Er EINVAL 241.Dv O_RDONLY 242was specified while creating an anonymous shared memory object via 243.Dv SHM_ANON . 244.It Bq Er EFAULT 245The 246.Fa path 247argument points outside the process' allocated address space. 248.It Bq Er ENAMETOOLONG 249The entire pathname exceeded 1023 characters. 250.It Bq Er EINVAL 251The 252.Fa path 253does not begin with a slash 254.Pq Ql \&/ 255character. 256.It Bq Er ENOENT 257.Dv O_CREAT 258is specified and the named shared memory object does not exist. 259.It Bq Er EEXIST 260.Dv O_CREAT 261and 262.Dv O_EXCL 263are specified and the named shared memory object does exist. 264.It Bq Er EACCES 265The required permissions (for reading or reading and writing) are denied. 266.El 267.Pp 268.Fn shm_unlink 269fails with these error codes for these conditions: 270.Bl -tag -width Er 271.It Bq Er EFAULT 272The 273.Fa path 274argument points outside the process' allocated address space. 275.It Bq Er ENAMETOOLONG 276The entire pathname exceeded 1023 characters. 277.It Bq Er ENOENT 278The named shared memory object does not exist. 279.It Bq Er EACCES 280The required permissions are denied. 281.Fn shm_unlink 282requires write permission to the shared memory object. 283.El 284.Sh SEE ALSO 285.Xr close 2 , 286.Xr fstat 2 , 287.Xr ftruncate 2 , 288.Xr mmap 2 , 289.Xr munmap 2 , 290.Xr sendfile 2 291.Sh STANDARDS 292The 293.Fn shm_open 294and 295.Fn shm_unlink 296functions are believed to conform to 297.St -p1003.1b-93 . 298.Sh HISTORY 299The 300.Fn shm_open 301and 302.Fn shm_unlink 303functions first appeared in 304.Fx 4.3 . 305The functions were reimplemented as system calls using shared memory objects 306directly rather than files in 307.Fx 8.0 . 308.Sh AUTHORS 309.An Garrett A. Wollman Aq Mt [email protected] 310(C library support and this manual page) 311.Pp 312.An Matthew Dillon Aq Mt [email protected] 313.Pq Dv MAP_NOSYNC 314