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