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 September 26, 2019 32.Dt SHM_OPEN 2 33.Os 34.Sh NAME 35.Nm memfd_create , shm_open , shm_rename, 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 memfd_create "const char *name" "unsigned int flags" 45.Ft int 46.Fn shm_open "const char *path" "int flags" "mode_t mode" 47.Ft int 48.Fn shm_rename "const char *path_from" "const char *path_to" "int flags" 49.Ft int 50.Fn shm_unlink "const char *path" 51.Sh DESCRIPTION 52The 53.Fn shm_open 54system call opens (or optionally creates) a 55.Tn POSIX 56shared memory object named 57.Fa path . 58The 59.Fa flags 60argument contains a subset of the flags used by 61.Xr open 2 . 62An access mode of either 63.Dv O_RDONLY 64or 65.Dv O_RDWR 66must be included in 67.Fa flags . 68The optional flags 69.Dv O_CREAT , 70.Dv O_EXCL , 71and 72.Dv O_TRUNC 73may also be specified. 74.Pp 75If 76.Dv O_CREAT 77is specified, 78then a new shared memory object named 79.Fa path 80will be created if it does not exist. 81In this case, 82the shared memory object is created with mode 83.Fa mode 84subject to the process' umask value. 85If both the 86.Dv O_CREAT 87and 88.Dv O_EXCL 89flags are specified and a shared memory object named 90.Fa path 91already exists, 92then 93.Fn shm_open 94will fail with 95.Er EEXIST . 96.Pp 97Newly created objects start off with a size of zero. 98If an existing shared memory object is opened with 99.Dv O_RDWR 100and the 101.Dv O_TRUNC 102flag is specified, 103then the shared memory object will be truncated to a size of zero. 104The size of the object can be adjusted via 105.Xr ftruncate 2 106and queried via 107.Xr fstat 2 . 108.Pp 109The new descriptor is set to close during 110.Xr execve 2 111system calls; 112see 113.Xr close 2 114and 115.Xr fcntl 2 . 116.Pp 117As a 118.Fx 119extension, the constant 120.Dv SHM_ANON 121may be used for the 122.Fa path 123argument to 124.Fn shm_open . 125In this case, an anonymous, unnamed shared memory object is created. 126Since the object has no name, 127it cannot be removed via a subsequent call to 128.Fn shm_unlink , 129or moved with a call to 130.Fn shm_rename . 131Instead, 132the shared memory object will be garbage collected when the last reference to 133the shared memory object is removed. 134The shared memory object may be shared with other processes by sharing the 135file descriptor via 136.Xr fork 2 137or 138.Xr sendmsg 2 . 139Attempting to open an anonymous shared memory object with 140.Dv O_RDONLY 141will fail with 142.Er EINVAL . 143All other flags are ignored. 144.Pp 145The 146.Fn shm_rename 147system call atomically removes a shared memory object named 148.Fa path_from 149and relinks it at 150.Fa path_to . 151If another object is already linked at 152.Fa path_to , 153that object will be unlinked, unless one of the following flags are provided: 154.Bl -tag -offset indent -width Er 155.It Er SHM_RENAME_EXCHANGE 156Atomically exchange the shms at 157.Fa path_from 158and 159.Fa path_to . 160.It Er SHM_RENAME_NOREPLACE 161Return an error if an shm exists at 162.Fa path_to , 163rather than unlinking it. 164.El 165.Fn shm_rename 166is also a 167.Fx 168extension. 169.Pp 170The 171.Fn shm_unlink 172system call removes a shared memory object named 173.Fa path . 174.Pp 175The 176.Fn memfd_create 177function creates an anonymous shared memory object, identical to that created 178by 179.Fn shm_open 180when 181.Dv SHM_ANON 182is specified. 183Newly created objects start off with a size of zero. 184The size of the new object must be adjusted via 185.Xr ftruncate 2 . 186.Pp 187The 188.Fa name 189argument must not be 190.Dv NULL , 191but it may be an empty string. 192The length of the 193.Fa name 194argument may not exceed 195.Dv NAME_MAX 196minus six characters for the prefix 197.Dq memfd: , 198which will be prepended. 199The 200.Fa name 201argument is intended solely for debugging purposes and will never be used by the 202kernel to identify a memfd. 203Names are therefore not required to be unique. 204.Pp 205The following 206.Fa flags 207may be specified to 208.Fn memfd_create : 209.Bl -tag -width MFD_ALLOW_SEALING 210.It Dv MFD_CLOEXEC 211Set 212.Dv FD_CLOEXEC 213on the resulting file descriptor. 214.It Dv MFD_ALLOW_SEALING 215Allow adding seals to the resulting file descriptor using the 216.Dv F_ADD_SEALS 217.Xr fcntl 2 218command. 219.It Dv MFD_HUGETLB 220This flag is currently unsupported. 221.El 222.Sh RETURN VALUES 223If successful, 224.Fn memfd_create 225and 226.Fn shm_open 227both return a non-negative integer, 228and 229.Fn shm_rename 230and 231.Fn shm_unlink 232return zero. 233All functions return -1 on failure, and set 234.Va errno 235to indicate the error. 236.Sh COMPATIBILITY 237The 238.Fa path , 239.Fa path_from , 240and 241.Fa path_to 242arguments do not necessarily represent a pathname (although they do in 243most other implementations). 244Two processes opening the same 245.Fa path 246are guaranteed to access the same shared memory object if and only if 247.Fa path 248begins with a slash 249.Pq Ql \&/ 250character. 251.Pp 252Only the 253.Dv O_RDONLY , 254.Dv O_RDWR , 255.Dv O_CREAT , 256.Dv O_EXCL , 257and 258.Dv O_TRUNC 259flags may be used in portable programs. 260.Pp 261.Tn POSIX 262specifications state that the result of using 263.Xr open 2 , 264.Xr read 2 , 265or 266.Xr write 2 267on a shared memory object, or on the descriptor returned by 268.Fn shm_open , 269is undefined. 270However, the 271.Fx 272kernel implementation explicitly includes support for 273.Xr read 2 274and 275.Xr write 2 . 276.Pp 277.Fx 278also supports zero-copy transmission of data from shared memory 279objects with 280.Xr sendfile 2 . 281.Pp 282Neither shared memory objects nor their contents persist across reboots. 283.Pp 284Writes do not extend shared memory objects, so 285.Xr ftruncate 2 286must be called before any data can be written. 287See 288.Sx EXAMPLES . 289.Sh EXAMPLES 290This example fails without the call to 291.Xr ftruncate 2 : 292.Bd -literal -compact 293 294 uint8_t buffer[getpagesize()]; 295 ssize_t len; 296 int fd; 297 298 fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); 299 if (fd < 0) 300 err(EX_OSERR, "%s: shm_open", __func__); 301 if (ftruncate(fd, getpagesize()) < 0) 302 err(EX_IOERR, "%s: ftruncate", __func__); 303 len = pwrite(fd, buffer, getpagesize(), 0); 304 if (len < 0) 305 err(EX_IOERR, "%s: pwrite", __func__); 306 if (len != getpagesize()) 307 errx(EX_IOERR, "%s: pwrite length mismatch", __func__); 308.Ed 309.Sh ERRORS 310.Fn memfd_create 311fails with these error codes for these conditions: 312.Bl -tag -width Er 313.It Bq Er EBADF 314The 315.Fa name 316argument was NULL. 317.It Bq Er EINVAL 318The 319.Fa name 320argument was too long. 321.Pp 322An invalid or unsupported flag was included in 323.Fa flags . 324.It Bq Er EMFILE 325The process has already reached its limit for open file descriptors. 326.It Bq Er ENFILE 327The system file table is full. 328.It Bq Er ENOSYS 329In 330.Fa memfd_create , 331.Dv MFD_HUGETLB 332was specified in 333.Fa flags , 334and this system does not support forced hugetlb mappings. 335.El 336.Pp 337.Fn shm_open 338fails with these error codes for these conditions: 339.Bl -tag -width Er 340.It Bq Er EINVAL 341A flag other than 342.Dv O_RDONLY , 343.Dv O_RDWR , 344.Dv O_CREAT , 345.Dv O_EXCL , 346or 347.Dv O_TRUNC 348was included in 349.Fa flags . 350.It Bq Er EMFILE 351The process has already reached its limit for open file descriptors. 352.It Bq Er ENFILE 353The system file table is full. 354.It Bq Er EINVAL 355.Dv O_RDONLY 356was specified while creating an anonymous shared memory object via 357.Dv SHM_ANON . 358.It Bq Er EFAULT 359The 360.Fa path 361argument points outside the process' allocated address space. 362.It Bq Er ENAMETOOLONG 363The entire pathname exceeds 1023 characters. 364.It Bq Er EINVAL 365The 366.Fa path 367does not begin with a slash 368.Pq Ql \&/ 369character. 370.It Bq Er ENOENT 371.Dv O_CREAT 372is not specified and the named shared memory object does not exist. 373.It Bq Er EEXIST 374.Dv O_CREAT 375and 376.Dv O_EXCL 377are specified and the named shared memory object does exist. 378.It Bq Er EACCES 379The required permissions (for reading or reading and writing) are denied. 380.El 381.Pp 382The following errors are defined for 383.Fn shm_rename : 384.Bl -tag -width Er 385.It Bq Er EFAULT 386The 387.Fa path_from 388or 389.Fa path_to 390argument points outside the process' allocated address space. 391.It Bq Er ENAMETOOLONG 392The entire pathname exceeds 1023 characters. 393.It Bq Er ENOENT 394The shared memory object at 395.Fa path_from 396does not exist. 397.It Bq Er EACCES 398The required permissions are denied. 399.It Bq Er EEXIST 400An shm exists at 401.Fa path_to , 402and the 403.Dv SHM_RENAME_NOREPLACE 404flag was provided. 405.El 406.Pp 407.Fn shm_unlink 408fails with these error codes for these conditions: 409.Bl -tag -width Er 410.It Bq Er EFAULT 411The 412.Fa path 413argument points outside the process' allocated address space. 414.It Bq Er ENAMETOOLONG 415The entire pathname exceeds 1023 characters. 416.It Bq Er ENOENT 417The named shared memory object does not exist. 418.It Bq Er EACCES 419The required permissions are denied. 420.Fn shm_unlink 421requires write permission to the shared memory object. 422.El 423.Sh SEE ALSO 424.Xr close 2 , 425.Xr fstat 2 , 426.Xr ftruncate 2 , 427.Xr mmap 2 , 428.Xr munmap 2 , 429.Xr sendfile 2 430.Sh STANDARDS 431The 432.Fn memfd_create 433function is expected to be compatible with the Linux system call of the same 434name. 435.Pp 436The 437.Fn shm_open 438and 439.Fn shm_unlink 440functions are believed to conform to 441.St -p1003.1b-93 . 442.Sh HISTORY 443The 444.Fn memfd_create 445function appeared in 446.Fx 13.0 . 447.Pp 448The 449.Fn shm_open 450and 451.Fn shm_unlink 452functions first appeared in 453.Fx 4.3 . 454The functions were reimplemented as system calls using shared memory objects 455directly rather than files in 456.Fx 8.0 . 457.Pp 458.Fn shm_rename 459first appeared in 460.Fx 13.0 461as a 462.Fx 463extension. 464.Sh AUTHORS 465.An Garrett A. Wollman Aq Mt [email protected] 466(C library support and this manual page) 467.Pp 468.An Matthew Dillon Aq Mt [email protected] 469.Pq Dv MAP_NOSYNC 470.Pp 471.An Matthew Bryan Aq Mt [email protected] 472.Pq Dv shm_rename implementation 473