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
33 .Nm memfd_create , shm_create_largepage , shm_open , shm_rename, shm_unlink
34 .Nd "shared memory object operations"
42 .Fn memfd_create "const char *name" "unsigned int flags"
44 .Fo shm_create_largepage
45 .Fa "const char *path"
48 .Fa "int alloc_policy"
52 .Fn shm_open "const char *path" "int flags" "mode_t mode"
54 .Fn shm_rename "const char *path_from" "const char *path_to" "int flags"
56 .Fn shm_unlink "const char *path"
60 function opens (or optionally creates) a
62 shared memory object named
66 argument contains a subset of the flags used by
68 An access mode of either
79 may also be specified.
84 then a new shared memory object named
86 will be created if it does not exist.
88 the shared memory object is created with mode
90 subject to the process' umask value.
95 flags are specified and a shared memory object named
103 Newly created objects start off with a size of zero.
104 If an existing shared memory object is opened with
109 then the shared memory object will be truncated to a size of zero.
110 The size of the object can be adjusted via
115 The new descriptor is set to close during
129 In this case, an anonymous, unnamed shared memory object is created.
130 Since the object has no name,
131 it cannot be removed via a subsequent call to
133 or moved with a call to
136 the shared memory object will be garbage collected when the last reference to
137 the shared memory object is removed.
138 The shared memory object may be shared with other processes by sharing the
143 Attempting to open an anonymous shared memory object with
147 All other flags are ignored.
150 .Fn shm_create_largepage
151 function behaves similarly to
155 flag is implicitly specified, and the returned
157 object is always backed by aligned, physically contiguous chunks of memory.
158 This ensures that the object can be mapped using so-called
160 which can improve application performance in some workloads by reducing the
161 number of translation lookaside buffer (TLB) entries required to access a
162 mapping of the object,
163 and by reducing the number of page faults performed when accessing a mapping.
164 This happens automatically for all largepage objects.
166 An existing largepage object can be opened using the
169 Largepage shared memory objects behave slightly differently from non-largepage
171 .Bl -bullet -offset indent
173 Memory for a largepage object is allocated when the object is
176 system call, whereas memory for regular shared memory objects is allocated
177 lazily and may be paged out to a swap device when not in use.
179 The size of a mapping of a largepage object must be a multiple of the
180 underlying large page size.
181 Most attributes of such a mapping can only be modified at the granularity
182 of the large page size.
183 For example, when using
185 to unmap a portion of a largepage object mapping, or when using
187 to adjust protections of a mapping of a largepage object, the starting address
188 must be large page size-aligned, and the length of the operation must be a
189 multiple of the large page size.
190 If not, the corresponding system call will fail and set
199 .Fn shm_create_largepage
200 specifies the size of large pages used to back the object.
201 This argument is an index into the page sizes array returned by
203 In particular, all large pages backing a largepage object must be of the
205 For example, on a system with large page sizes of 2MB and 1GB, a 2GB largepage
206 object will consist of either 1024 2MB pages, or 2 1GB pages, depending on
207 the value specified for the
212 parameter specifies what happens when an attempt to use
214 to allocate memory for the object fails.
215 The following values are accepted:
216 .Bl -tag -offset indent -width SHM_
217 .It Dv SHM_LARGEPAGE_ALLOC_DEFAULT
218 If the (non-blocking) memory allocation fails because there is insufficient free
219 contiguous memory, the kernel will attempt to defragment physical memory and
220 try another allocation.
221 The subsequent allocation may or may not succeed.
222 If this subsequent allocation also fails,
228 .It Dv SHM_LARGEPAGE_ALLOC_NOWAIT
229 If the memory allocation fails,
235 .It Dv SHM_LARGEPAGE_ALLOC_HARD
236 The kernel will attempt defragmentation until the allocation succeeds,
237 or an unblocked signal is delivered to the thread.
238 However, it is possible for physical memory to be fragmented such that the
239 allocation will never succeed.
247 commands can be used with a largepage shared memory object to get and set
248 largepage object parameters.
249 Both commands operate on the following structure:
251 struct shm_largepage_conf {
259 command populates this structure with the current values of these parameters,
262 command modifies the largepage object.
265 parameter may be modified.
267 .Fn shm_create_largepage
268 works by creating a regular shared memory object using
270 and then converting it into a largepage object using the
276 system call atomically removes a shared memory object named
280 If another object is already linked at
282 that object will be unlinked, unless one of the following flags are provided:
283 .Bl -tag -offset indent -width Er
284 .It Er SHM_RENAME_EXCHANGE
285 Atomically exchange the shms at
289 .It Er SHM_RENAME_NOREPLACE
290 Return an error if an shm exists at
292 rather than unlinking it.
297 system call removes a shared memory object named
302 function creates an anonymous shared memory object, identical to that created
308 Newly created objects start off with a size of zero.
309 The size of the new object must be adjusted via
316 but it may be an empty string.
319 argument may not exceed
321 minus six characters for the prefix
323 which will be prepended.
326 argument is intended solely for debugging purposes and will never be used by the
327 kernel to identify a memfd.
328 Names are therefore not required to be unique.
334 .Bl -tag -width MFD_ALLOW_SEALING
338 on the resulting file descriptor.
339 .It Dv MFD_ALLOW_SEALING
340 Allow adding seals to the resulting file descriptor using the
345 This flag is currently unsupported.
352 both return a non-negative integer,
358 All functions return -1 on failure, and set
360 to indicate the error.
363 .Fn shm_create_largepage
368 extensions, as is support for the
378 arguments do not necessarily represent a pathname (although they do in
379 most other implementations).
380 Two processes opening the same
382 are guaranteed to access the same shared memory object if and only if
395 flags may be used in portable programs.
398 specifications state that the result of using
403 on a shared memory object, or on the descriptor returned by
408 kernel implementation explicitly includes support for
414 also supports zero-copy transmission of data from shared memory
418 Neither shared memory objects nor their contents persist across reboots.
420 Writes do not extend shared memory objects, so
422 must be called before any data can be written.
426 This example fails without the call to
428 .Bd -literal -compact
430 uint8_t buffer[getpagesize()];
434 fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600);
436 err(EX_OSERR, "%s: shm_open", __func__);
437 if (ftruncate(fd, getpagesize()) < 0)
438 err(EX_IOERR, "%s: ftruncate", __func__);
439 len = pwrite(fd, buffer, getpagesize(), 0);
441 err(EX_IOERR, "%s: pwrite", __func__);
442 if (len != getpagesize())
443 errx(EX_IOERR, "%s: pwrite length mismatch", __func__);
447 fails with these error codes for these conditions:
456 argument was too long.
458 An invalid or unsupported flag was included in
461 The process has already reached its limit for open file descriptors.
463 The system file table is full.
470 and this system does not support forced hugetlb mappings.
474 fails with these error codes for these conditions:
487 The process has already reached its limit for open file descriptors.
489 The system file table is full.
492 was specified while creating an anonymous shared memory object via
497 argument points outside the process' allocated address space.
498 .It Bq Er ENAMETOOLONG
499 The entire pathname exceeds 1023 characters.
503 does not begin with a slash
508 is not specified and the named shared memory object does not exist.
513 are specified and the named shared memory object does exist.
515 The required permissions (for reading or reading and writing) are denied.
517 The process is running in capability mode (see
519 and attempted to create a named shared memory object.
522 .Fn shm_create_largepage
523 can fail for the reasons listed above.
524 It also fails with these error codes for the following conditions:
527 The kernel does not support large pages on the current platform.
530 The following errors are defined for
538 argument points outside the process' allocated address space.
539 .It Bq Er ENAMETOOLONG
540 The entire pathname exceeds 1023 characters.
542 The shared memory object at
546 The required permissions are denied.
551 .Dv SHM_RENAME_NOREPLACE
556 fails with these error codes for these conditions:
561 argument points outside the process' allocated address space.
562 .It Bq Er ENAMETOOLONG
563 The entire pathname exceeds 1023 characters.
565 The named shared memory object does not exist.
567 The required permissions are denied.
569 requires write permission to the shared memory object.
572 .Xr posixshmcontrol 1 ,
583 function is expected to be compatible with the Linux system call of the same
590 functions are believed to conform to
602 functions first appeared in
604 The functions were reimplemented as system calls using shared memory objects
605 directly rather than files in
615 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
616 (C library support and this manual page)
618 .An Matthew Dillon Aq Mt dillon@FreeBSD.org
621 .An Matthew Bryan Aq Mt matthew.bryan@isilon.com
622 .Pq Dv shm_rename implementation