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