Struct ndk::shared_memory::SharedMemory

source ·

pub struct SharedMemory(/* private fields */);

Available on crate feature api-level-26 only.

Expand description

Enables the creation, mapping, and protection control over anonymous shared memory.

Implementations§

source §

impl SharedMemory

source

pub fn create(name: Option<&CStr>, size: usize) -> Result<Self>

Create a shared memory region.

Creates shared memory region and returns a file descriptor. The resulting file descriptor can be mmap’ed to process memory space with PROT_READ | PROT_WRITE | PROT_EXEC. Access to this shared memory region can be restricted with set_prot().

Use android.os.ParcelFileDescriptor to pass the file descriptor to another process. File descriptors may also be sent to other processes over a Unix domain socket with sendmsg and SCM_RIGHTS. See sendmsg(3) and cmsg(3) man pages for more information.

If you intend to share this file descriptor with a child process after calling exec(3), note that you will need to use fcntl(2) with F_SETFD to clear the FD_CLOEXEC flag for this to work on all versions of Android.

source

pub fn dup_from_java(env: *mut JNIEnv, shared_memory: jobject) -> Result<Self>

Available on crate feature api-level-27 only.

Returns a dup’d FD from the given Java android.os.SharedMemory object.

The returned file descriptor has all the same properties & capabilities as the FD returned from create(), however the protection flags will be the same as those of the android.os.SharedMemory object.

source

pub fn size(&self) -> usize

Get the size of the shared memory region.

source

pub fn set_prot(&self, prot: i32) -> Result<()>

Restrict access of shared memory region.

This function restricts access of a shared memory region. Access can only be removed. The effect applies globally to all file descriptors in all processes across the system that refer to this shared memory region. Existing memory mapped regions are not affected.

It is a common use case to create a shared memory region, map it read/write locally to initialize content, and then send the shared memory to another process with read only access. Code example as below:

let mem = SharedMemory::create(Some(CStr::from_bytes_with_nul_unchecked(b"memory\0")), 127).unwrap();
// By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
let size = mem.size();
let buffer = libc::mmap(
    std::ptr::null_mut(),
    size,
    libc::PROT_READ | libc::PROT_WRITE,
    libc::MAP_SHARED,
    mem.as_raw_fd(),
    0,
);
let buffer_slice = std::slice::from_raw_parts_mut(buffer.cast(), size);

// trivially initialize content
buffer_slice[..7].copy_from_slice(b"hello!\0");

// Existing mappings will retain their protection flags (PROT_WRITE here) after set_prod()
// unless it is unmapped:
libc::munmap(buffer, size);

// limit access to read only
mem.set_prot(libc::PROT_READ);

// share fd with another process here and the other process can only map with PROT_READ.