rustix/
shm.rs

1//! POSIX shared memory
2//!
3//! # Examples
4//!
5//! ```
6//! use rustix::fs::{ftruncate, Mode};
7//! use rustix::mm::{mmap, MapFlags, ProtFlags};
8//! use rustix::{io, shm};
9//! use std::mem::size_of;
10//! use std::ptr::null_mut;
11//!
12//! # fn example() -> io::Result<()> {
13//! // A type describing the data to be shared.
14//! #[repr(C)]
15//! struct MyBufferType {
16//!     // …
17//! }
18//!
19//! // Create the shared memory object.
20//! let shm_path = "/rustix-shm-example";
21//! let fd = shm::open(
22//!     shm_path,
23//!     shm::OFlags::CREATE | shm::OFlags::EXCL | shm::OFlags::RDWR,
24//!     Mode::RUSR | Mode::WUSR,
25//! )?;
26//!
27//! // Resize the shared memory object to the size of our data.
28//! ftruncate(&fd, size_of::<MyBufferType>() as u64)?;
29//!
30//! // Map the shared memory object into our address space.
31//! //
32//! // SAFETY: We're creating a new mapping that's independent of any existing
33//! // memory allocations. There are interesting things to say about *using*
34//! // `ptr`, but that's for another safety comment.
35//! let ptr = unsafe {
36//!     mmap(
37//!         null_mut(),
38//!         size_of::<MyBufferType>(),
39//!         ProtFlags::READ | ProtFlags::WRITE,
40//!         MapFlags::SHARED,
41//!         &fd,
42//!         0,
43//!     )?
44//! };
45//!
46//! // Use `ptr`…
47//!
48//! // Remove the shared memory object name.
49//! shm::unlink(shm_path)?;
50//! # Ok(())
51//! # }
52//! ```
53
54#![allow(unused_qualifications)]
55
56use crate::fd::OwnedFd;
57use crate::{backend, io, path};
58
59use super::shm;
60pub use crate::backend::fs::types::Mode;
61pub use crate::backend::shm::types::ShmOFlags as OFlags;
62
63/// `shm_open(name, oflags, mode)`—Opens a shared memory object.
64///
65/// For portability, `name` should begin with a slash, contain no other
66/// slashes, and be no longer than an implementation-defined limit (255 on
67/// Linux).
68///
69/// Exactly one of [`shm::OFlags::RDONLY`] and [`shm::OFlags::RDWR`] should be
70/// passed. The file descriptor will be opened with `FD_CLOEXEC` set.
71///
72/// # References
73///  - [POSIX]
74///  - [Linux]
75///
76/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/shm_open.html
77/// [Linux]: https://man7.org/linux/man-pages/man3/shm_open.3.html
78#[doc(alias = "shm_open")]
79#[inline]
80pub fn open<P: path::Arg>(name: P, flags: shm::OFlags, mode: Mode) -> io::Result<OwnedFd> {
81    name.into_with_c_str(|name| backend::shm::syscalls::shm_open(name, flags, mode))
82}
83
84/// `shm_unlink(name)`—Unlinks a shared memory object.
85///
86/// # References
87///  - [POSIX]
88///  - [Linux]
89///
90/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/shm_unlink.html
91/// [Linux]: https://man7.org/linux/man-pages/man3/shm_unlink.3.html
92#[doc(alias = "shm_unlink")]
93#[inline]
94pub fn unlink<P: path::Arg>(name: P) -> io::Result<()> {
95    name.into_with_c_str(backend::shm::syscalls::shm_unlink)
96}
rustix/shm.rs

rustix/
shm.rs
