2 .\" Copyright 2000 Massachusetts Institute of Technology
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
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
31 .Dd September 26, 2019
35 .Nm memfd_create , shm_open , shm_rename, shm_unlink
36 .Nd "shared memory object operations"
44 .Fn memfd_create "const char *name" "unsigned int flags"
46 .Fn shm_open "const char *path" "int flags" "mode_t mode"
48 .Fn shm_rename "const char *path_from" "const char *path_to" "int flags"
50 .Fn shm_unlink "const char *path"
54 system call opens (or optionally creates) a
56 shared memory object named
60 argument contains a subset of the flags used by
62 An access mode of either
73 may also be specified.
78 then a new shared memory object named
80 will be created if it does not exist.
82 the shared memory object is created with mode
84 subject to the process' umask value.
89 flags are specified and a shared memory object named
97 Newly created objects start off with a size of zero.
98 If an existing shared memory object is opened with
103 then the shared memory object will be truncated to a size of zero.
104 The size of the object can be adjusted via
109 The new descriptor is set to close during
119 extension, the constant
125 In this case, an anonymous, unnamed shared memory object is created.
126 Since the object has no name,
127 it cannot be removed via a subsequent call to
129 or moved with a call to
132 the shared memory object will be garbage collected when the last reference to
133 the shared memory object is removed.
134 The shared memory object may be shared with other processes by sharing the
139 Attempting to open an anonymous shared memory object with
143 All other flags are ignored.
147 system call atomically removes a shared memory object named
151 If another object is already linked at
153 that 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
156 Atomically exchange the shms at
160 .It Er SHM_RENAME_NOREPLACE
161 Return an error if an shm exists at
163 rather than unlinking it.
172 system call removes a shared memory object named
177 function creates an anonymous shared memory object, identical to that created
183 Newly created objects start off with a size of zero.
184 The size of the new object must be adjusted via
191 but it may be an empty string.
194 argument may not exceed
196 minus six characters for the prefix
198 which will be prepended.
201 argument is intended solely for debugging purposes and will never be used by the
202 kernel to identify a memfd.
203 Names are therefore not required to be unique.
209 .Bl -tag -width MFD_ALLOW_SEALING
213 on the resulting file descriptor.
214 .It Dv MFD_ALLOW_SEALING
215 Allow adding seals to the resulting file descriptor using the
220 This flag is currently unsupported.
227 both return a non-negative integer,
233 All functions return -1 on failure, and set
235 to indicate the error.
242 arguments do not necessarily represent a pathname (although they do in
243 most other implementations).
244 Two processes opening the same
246 are guaranteed to access the same shared memory object if and only if
259 flags may be used in portable programs.
262 specifications state that the result of using
267 on a shared memory object, or on the descriptor returned by
272 kernel implementation explicitly includes support for
278 also supports zero-copy transmission of data from shared memory
282 Neither shared memory objects nor their contents persist across reboots.
284 Writes do not extend shared memory objects, so
286 must be called before any data can be written.
290 This example fails without the call to
292 .Bd -literal -compact
294 uint8_t buffer[getpagesize()];
298 fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600);
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);
305 err(EX_IOERR, "%s: pwrite", __func__);
306 if (len != getpagesize())
307 errx(EX_IOERR, "%s: pwrite length mismatch", __func__);
311 fails with these error codes for these conditions:
320 argument was too long.
322 An invalid or unsupported flag was included in
325 The process has already reached its limit for open file descriptors.
327 The system file table is full.
334 and this system does not support forced hugetlb mappings.
338 fails with these error codes for these conditions:
351 The process has already reached its limit for open file descriptors.
353 The system file table is full.
356 was specified while creating an anonymous shared memory object via
361 argument points outside the process' allocated address space.
362 .It Bq Er ENAMETOOLONG
363 The entire pathname exceeds 1023 characters.
367 does not begin with a slash
372 is specified and the named shared memory object does not exist.
377 are specified and the named shared memory object does exist.
379 The required permissions (for reading or reading and writing) are denied.
382 The following errors are defined for
390 argument points outside the process' allocated address space.
391 .It Bq Er ENAMETOOLONG
392 The entire pathname exceeds 1023 characters.
394 The shared memory object at
398 The required permissions are denied.
403 .Dv SHM_RENAME_NOREPLACE
408 fails with these error codes for these conditions:
413 argument points outside the process' allocated address space.
414 .It Bq Er ENAMETOOLONG
415 The entire pathname exceeds 1023 characters.
417 The named shared memory object does not exist.
419 The required permissions are denied.
421 requires write permission to the shared memory object.
433 function is expected to be compatible with the Linux system call of the same
440 functions are believed to conform to
452 functions first appeared in
454 The functions were reimplemented as system calls using shared memory objects
455 directly rather than files in
465 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
466 (C library support and this manual page)
468 .An Matthew Dillon Aq Mt dillon@FreeBSD.org
471 .An Matthew Bryan Aq Mt matthew.bryan@isilon.com
472 .Pq Dv shm_rename implementation