lib/libc/sys/shm_open.2

   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 .Dd January 30, 2023
  30 .Dt SHM_OPEN 2
  31 .Os
  32 .Sh NAME
  33 .Nm memfd_create , shm_create_largepage , shm_open , shm_rename, shm_unlink
  34 .Nd "shared memory object operations"
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/mman.h
  40 .In fcntl.h
  41 .Ft int
  42 .Fn memfd_create "const char *name" "unsigned int flags"
  43 .Ft int
  44 .Fo shm_create_largepage
  45 .Fa "const char *path"
  46 .Fa "int flags"
  47 .Fa "int psind"
  48 .Fa "int alloc_policy"
  49 .Fa "mode_t mode"
  50 .Fc
  51 .Ft int
  52 .Fn shm_open "const char *path" "int flags" "mode_t mode"
  53 .Ft int
  54 .Fn shm_rename "const char *path_from" "const char *path_to" "int flags"
  55 .Ft int
  56 .Fn shm_unlink "const char *path"
  57 .Sh DESCRIPTION
  58 The
  59 .Fn shm_open
  60 function opens (or optionally creates) a
  61 POSIX
  62 shared memory object named
  63 .Fa path .
  64 The
  65 .Fa flags
  66 argument contains a subset of the flags used by
  67 .Xr open 2 .
  68 An access mode of either
  69 .Dv O_RDONLY
  70 or
  71 .Dv O_RDWR
  72 must be included in
  73 .Fa flags .
  74 The optional flags
  75 .Dv O_CREAT ,
  76 .Dv O_EXCL ,
  77 and
  78 .Dv O_TRUNC
  79 may also be specified.
  80 .Pp
  81 If
  82 .Dv O_CREAT
  83 is specified,
  84 then a new shared memory object named
  85 .Fa path
  86 will be created if it does not exist.
  87 In this case,
  88 the shared memory object is created with mode
  89 .Fa mode
  90 subject to the process' umask value.
  91 If both the
  92 .Dv O_CREAT
  93 and
  94 .Dv O_EXCL
  95 flags are specified and a shared memory object named
  96 .Fa path
  97 already exists,
  98 then
  99 .Fn shm_open
 100 will fail with
 101 .Er EEXIST .
 102 .Pp
 103 Newly created objects start off with a size of zero.
 104 If an existing shared memory object is opened with
 105 .Dv O_RDWR
 106 and the
 107 .Dv O_TRUNC
 108 flag is specified,
 109 then the shared memory object will be truncated to a size of zero.
 110 The size of the object can be adjusted via
 111 .Xr ftruncate 2
 112 and queried via
 113 .Xr fstat 2 .
 114 .Pp
 115 The new descriptor is set to close during
 116 .Xr execve 2
 117 system calls;
 118 see
 119 .Xr close 2
 120 and
 121 .Xr fcntl 2 .
 122 .Pp
 123 The constant
 124 .Dv SHM_ANON
 125 may be used for the
 126 .Fa path
 127 argument to
 128 .Fn shm_open .
 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
 132 .Fn shm_unlink ,
 133 or moved with a call to
 134 .Fn shm_rename .
 135 Instead,
 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
 139 file descriptor via
 140 .Xr fork 2
 141 or
 142 .Xr sendmsg 2 .
 143 Attempting to open an anonymous shared memory object with
 144 .Dv O_RDONLY
 145 will fail with
 146 .Er EINVAL .
 147 All other flags are ignored.
 148 .Pp
 149 The
 150 .Fn shm_create_largepage
 151 function behaves similarly to
 152 .Fn shm_open ,
 153 except that the
 154 .Dv O_CREAT
 155 flag is implicitly specified, and the returned
 156 .Dq largepage
 157 object is always backed by aligned, physically contiguous chunks of memory.
 158 This ensures that the object can be mapped using so-called
 159 .Dq superpages ,
 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.
 165 .Pp
 166 An existing largepage object can be opened using the
 167 .Fn shm_open
 168 function.
 169 Largepage shared memory objects behave slightly differently from non-largepage
 170 objects:
 171 .Bl -bullet -offset indent
 172 .It
 173 Memory for a largepage object is allocated when the object is
 174 extended using the
 175 .Xr ftruncate 2
 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.
 178 .It
 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
 184 .Xr munmap 2
 185 to unmap a portion of a largepage object mapping, or when using
 186 .Xr mprotect 2
 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
 191 .Va errno
 192 to
 193 .Er EINVAL .
 194 .El
 195 .Pp
 196 The
 197 .Fa psind
 198 argument to
 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
 202 .Xr getpagesizes 3 .
 203 In particular, all large pages backing a largepage object must be of the
 204 same size.
 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
 208 .Fa psind
 209 argument.
 210 The
 211 .Fa alloc_policy
 212 parameter specifies what happens when an attempt to use
 213 .Xr ftruncate 2
 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,
 223 .Xr ftruncate 2
 224 will fail and set
 225 .Va errno
 226 to
 227 .Er ENOMEM .
 228 .It Dv SHM_LARGEPAGE_ALLOC_NOWAIT
 229 If the memory allocation fails,
 230 .Xr ftruncate 2
 231 will fail and set
 232 .Va errno
 233 to
 234 .Er ENOMEM .
 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.
 240 .El
 241 .Pp
 242 The
 243 .Dv FIOSSHMLPGCNF
 244 and
 245 .Dv FIOGSHMLPGCNF
 246 .Xr ioctl 2
 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:
 250 .Bd -literal
 251 struct shm_largepage_conf {
 252         int psind;
 253         int alloc_policy;
 254 };
 255
 256 .Ed
 257 The
 258 .Dv FIOGSHMLPGCNF
 259 command populates this structure with the current values of these parameters,
 260 while the
 261 .Dv FIOSSHMLPGCNF
 262 command modifies the largepage object.
 263 Currently only the
 264 .Va alloc_policy
 265 parameter may be modified.
 266 Internally,
 267 .Fn shm_create_largepage
 268 works by creating a regular shared memory object using
 269 .Fn shm_open ,
 270 and then converting it into a largepage object using the
 271 .Dv FIOSSHMLPGCNF
 272 ioctl command.
 273 .Pp
 274 The
 275 .Fn shm_rename
 276 system call atomically removes a shared memory object named
 277 .Fa path_from
 278 and relinks it at
 279 .Fa path_to .
 280 If another object is already linked at
 281 .Fa path_to ,
 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
 286 .Fa path_from
 287 and
 288 .Fa path_to .
 289 .It Er SHM_RENAME_NOREPLACE
 290 Return an error if an shm exists at
 291 .Fa path_to ,
 292 rather than unlinking it.
 293 .El
 294 .Pp
 295 The
 296 .Fn shm_unlink
 297 system call removes a shared memory object named
 298 .Fa path .
 299 .Pp
 300 The
 301 .Fn memfd_create
 302 function creates an anonymous shared memory object, identical to that created
 303 by
 304 .Fn shm_open
 305 when
 306 .Dv SHM_ANON
 307 is specified.
 308 Newly created objects start off with a size of zero.
 309 The size of the new object must be adjusted via
 310 .Xr ftruncate 2 .
 311 .Pp
 312 The
 313 .Fa name
 314 argument must not be
 315 .Dv NULL ,
 316 but it may be an empty string.
 317 The length of the
 318 .Fa name
 319 argument may not exceed
 320 .Dv NAME_MAX
 321 minus six characters for the prefix
 322 .Dq memfd: ,
 323 which will be prepended.
 324 The
 325 .Fa name
 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.
 329 .Pp
 330 The following
 331 .Fa flags
 332 may be specified to
 333 .Fn memfd_create :
 334 .Bl -tag -width MFD_ALLOW_SEALING
 335 .It Dv MFD_CLOEXEC
 336 Set
 337 .Dv FD_CLOEXEC
 338 on the resulting file descriptor.
 339 .It Dv MFD_ALLOW_SEALING
 340 Allow adding seals to the resulting file descriptor using the
 341 .Dv F_ADD_SEALS
 342 .Xr fcntl 2
 343 command.
 344 .It Dv MFD_HUGETLB
 345 This flag is currently unsupported.
 346 .El
 347 .Sh RETURN VALUES
 348 If successful,
 349 .Fn memfd_create
 350 and
 351 .Fn shm_open
 352 both return a non-negative integer,
 353 and
 354 .Fn shm_rename
 355 and
 356 .Fn shm_unlink
 357 return zero.
 358 All functions return -1 on failure, and set
 359 .Va errno
 360 to indicate the error.
 361 .Sh COMPATIBILITY
 362 The
 363 .Fn shm_create_largepage
 364 and
 365 .Fn shm_rename
 366 functions are
 367 .Fx
 368 extensions, as is support for the
 369 .Dv SHM_ANON
 370 value in
 371 .Fn shm_open .
 372 .Pp
 373 The
 374 .Fa path ,
 375 .Fa path_from ,
 376 and
 377 .Fa path_to
 378 arguments do not necessarily represent a pathname (although they do in
 379 most other implementations).
 380 Two processes opening the same
 381 .Fa path
 382 are guaranteed to access the same shared memory object if and only if
 383 .Fa path
 384 begins with a slash
 385 .Pq Ql \&/
 386 character.
 387 .Pp
 388 Only the
 389 .Dv O_RDONLY ,
 390 .Dv O_RDWR ,
 391 .Dv O_CREAT ,
 392 .Dv O_EXCL ,
 393 and
 394 .Dv O_TRUNC
 395 flags may be used in portable programs.
 396 .Pp
 397 POSIX
 398 specifications state that the result of using
 399 .Xr open 2 ,
 400 .Xr read 2 ,
 401 or
 402 .Xr write 2
 403 on a shared memory object, or on the descriptor returned by
 404 .Fn shm_open ,
 405 is undefined.
 406 However, the
 407 .Fx
 408 kernel implementation explicitly includes support for
 409 .Xr read 2
 410 and
 411 .Xr write 2 .
 412 .Pp
 413 .Fx
 414 also supports zero-copy transmission of data from shared memory
 415 objects with
 416 .Xr sendfile 2 .
 417 .Pp
 418 Neither shared memory objects nor their contents persist across reboots.
 419 .Pp
 420 Writes do not extend shared memory objects, so
 421 .Xr ftruncate 2
 422 must be called before any data can be written.
 423 See
 424 .Sx EXAMPLES .
 425 .Sh EXAMPLES
 426 This example fails without the call to
 427 .Xr ftruncate 2 :
 428 .Bd -literal -compact
 429
 430         uint8_t buffer[getpagesize()];
 431         ssize_t len;
 432         int fd;
 433
 434         fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600);
 435         if (fd < 0)
 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);
 440         if (len < 0)
 441                 err(EX_IOERR, "%s: pwrite", __func__);
 442         if (len != getpagesize())
 443                 errx(EX_IOERR, "%s: pwrite length mismatch", __func__);
 444 .Ed
 445 .Sh ERRORS
 446 .Fn memfd_create
 447 fails with these error codes for these conditions:
 448 .Bl -tag -width Er
 449 .It Bq Er EBADF
 450 The
 451 .Fa name
 452 argument was NULL.
 453 .It Bq Er EINVAL
 454 The
 455 .Fa name
 456 argument was too long.
 457 .Pp
 458 An invalid or unsupported flag was included in
 459 .Fa flags .
 460 .It Bq Er EMFILE
 461 The process has already reached its limit for open file descriptors.
 462 .It Bq Er ENFILE
 463 The system file table is full.
 464 .It Bq Er ENOSYS
 465 In
 466 .Fa memfd_create ,
 467 .Dv MFD_HUGETLB
 468 was specified in
 469 .Fa flags ,
 470 and this system does not support forced hugetlb mappings.
 471 .El
 472 .Pp
 473 .Fn shm_open
 474 fails with these error codes for these conditions:
 475 .Bl -tag -width Er
 476 .It Bq Er EINVAL
 477 A flag other than
 478 .Dv O_RDONLY ,
 479 .Dv O_RDWR ,
 480 .Dv O_CREAT ,
 481 .Dv O_EXCL ,
 482 or
 483 .Dv O_TRUNC
 484 was included in
 485 .Fa flags .
 486 .It Bq Er EMFILE
 487 The process has already reached its limit for open file descriptors.
 488 .It Bq Er ENFILE
 489 The system file table is full.
 490 .It Bq Er EINVAL
 491 .Dv O_RDONLY
 492 was specified while creating an anonymous shared memory object via
 493 .Dv SHM_ANON .
 494 .It Bq Er EFAULT
 495 The
 496 .Fa path
 497 argument points outside the process' allocated address space.
 498 .It Bq Er ENAMETOOLONG
 499 The entire pathname exceeds 1023 characters.
 500 .It Bq Er EINVAL
 501 The
 502 .Fa path
 503 does not begin with a slash
 504 .Pq Ql \&/
 505 character.
 506 .It Bq Er ENOENT
 507 .Dv O_CREAT
 508 is not specified and the named shared memory object does not exist.
 509 .It Bq Er EEXIST
 510 .Dv O_CREAT
 511 and
 512 .Dv O_EXCL
 513 are specified and the named shared memory object does exist.
 514 .It Bq Er EACCES
 515 The required permissions (for reading or reading and writing) are denied.
 516 .It Bq Er ECAPMODE
 517 The process is running in capability mode (see
 518 .Xr capsicum 4 )
 519 and attempted to create a named shared memory object.
 520 .El
 521 .Pp
 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:
 525 .Bl -tag -width Er
 526 .It Bq Er ENOTTY
 527 The kernel does not support large pages on the current platform.
 528 .El
 529 .Pp
 530 The following errors are defined for
 531 .Fn shm_rename :
 532 .Bl -tag -width Er
 533 .It Bq Er EFAULT
 534 The
 535 .Fa path_from
 536 or
 537 .Fa path_to
 538 argument points outside the process' allocated address space.
 539 .It Bq Er ENAMETOOLONG
 540 The entire pathname exceeds 1023 characters.
 541 .It Bq Er ENOENT
 542 The shared memory object at
 543 .Fa path_from
 544 does not exist.
 545 .It Bq Er EACCES
 546 The required permissions are denied.
 547 .It Bq Er EEXIST
 548 An shm exists at
 549 .Fa path_to ,
 550 and the
 551 .Dv SHM_RENAME_NOREPLACE
 552 flag was provided.
 553 .El
 554 .Pp
 555 .Fn shm_unlink
 556 fails with these error codes for these conditions:
 557 .Bl -tag -width Er
 558 .It Bq Er EFAULT
 559 The
 560 .Fa path
 561 argument points outside the process' allocated address space.
 562 .It Bq Er ENAMETOOLONG
 563 The entire pathname exceeds 1023 characters.
 564 .It Bq Er ENOENT
 565 The named shared memory object does not exist.
 566 .It Bq Er EACCES
 567 The required permissions are denied.
 568 .Fn shm_unlink
 569 requires write permission to the shared memory object.
 570 .El
 571 .Sh SEE ALSO
 572 .Xr posixshmcontrol 1 ,
 573 .Xr close 2 ,
 574 .Xr fstat 2 ,
 575 .Xr ftruncate 2 ,
 576 .Xr ioctl 2 ,
 577 .Xr mmap 2 ,
 578 .Xr munmap 2 ,
 579 .Xr sendfile 2
 580 .Sh STANDARDS
 581 The
 582 .Fn memfd_create
 583 function is expected to be compatible with the Linux system call of the same
 584 name.
 585 .Pp
 586 The
 587 .Fn shm_open
 588 and
 589 .Fn shm_unlink
 590 functions are believed to conform to
 591 .St -p1003.1b-93 .
 592 .Sh HISTORY
 593 The
 594 .Fn memfd_create
 595 function appeared in
 596 .Fx 13.0 .
 597 .Pp
 598 The
 599 .Fn shm_open
 600 and
 601 .Fn shm_unlink
 602 functions first appeared in
 603 .Fx 4.3 .
 604 The functions were reimplemented as system calls using shared memory objects
 605 directly rather than files in
 606 .Fx 8.0 .
 607 .Pp
 608 .Fn shm_rename
 609 first appeared in
 610 .Fx 13.0
 611 as a
 612 .Fx
 613 extension.
 614 .Sh AUTHORS
 615 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
 616 (C library support and this manual page)
 617 .Pp
 618 .An Matthew Dillon Aq Mt dillon@FreeBSD.org
 619 .Pq Dv MAP_NOSYNC
 620 .Pp
 621 .An Matthew Bryan Aq Mt matthew.bryan@isilon.com
 622 .Pq Dv shm_rename implementation