Memory

Summary

Functions
`ASharedMemory_create(const char *name, size_t size)`	`int` Create a shared memory region.
`ASharedMemory_dupFromJava(JNIEnv *env, jobject sharedMemory)`	`int` Returns a dup'd FD from the given Java android.os.SharedMemory object.
`ASharedMemory_getSize(int fd)`	`size_t` Get the size of the shared memory region.
`ASharedMemory_setProt(int fd, int prot)`	`int` Restrict access of shared memory region.

Functions

ASharedMemory_create

Declared in android/sharedmem.h

int ASharedMemory_create(
  const char *name,
  size_t size
)

Create a shared memory region.

Create a shared memory region and returns a file descriptor. The resulting file descriptor can be mapped into the process' memory using mmap(2) with PROT_READ | PROT_WRITE | PROT_EXEC. Access to shared memory regions can be restricted with ASharedMemory_setProt.

Use close(2) to release the shared memory region.

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(2) 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.

Available since API level 26.

Details

Parameters

`name`	an optional name.
`size`	size of the shared memory region

Returns

file descriptor that denotes the shared memory; -1 and sets errno on failure, or -EINVAL if the error is that size was 0.

ASharedMemory_dupFromJava

Declared in android/sharedmem_jni.h

int ASharedMemory_dupFromJava(
  JNIEnv *env,
  jobject sharedMemory
)

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 ASharedMemory_create(), however the protection flags will be the same as those of the android.os.SharedMemory object.

Use close() to release the shared memory region.

Available since API level 27.

Details

Parameters

`env`	The JNIEnv* pointer
`sharedMemory`	The Java android.os.SharedMemory object

Returns

file descriptor that denotes the shared memory; -1 if the shared memory object is already closed, if the JNIEnv or jobject is NULL, or if there are too many open file descriptors (errno=EMFILE)

ASharedMemory_getSize

Declared in android/sharedmem.h

size_t ASharedMemory_getSize(
  int fd
)

Get the size of the shared memory region.

Available since API level 26.

Details

Parameters

`fd`	file descriptor of the shared memory region

Returns

size in bytes; 0 if fd is not a valid shared memory file descriptor.

ASharedMemory_setProt

Declared in android/sharedmem.h

int ASharedMemory_setProt(
  int fd,
  int prot
)

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 intialize content, and then send the shared memory to another process with read only access. Code example as below (error handling omited).

int fd = ASharedMemory_create("memory", 128);

// By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
size_t memSize = ASharedMemory_getSize(fd);
char *buffer = (char *) mmap(NULL, memSize, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);

strcpy(buffer, "This is an example."); // trivially initialize content

// limit access to read only
ASharedMemory_setProt(fd, PROT_READ);

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

Available since API level 26.

Details

Parameters

`fd`	file descriptor of the shared memory region.
`prot`	any bitwise-or'ed combination of `PROT_READ`, `PROT_WRITE`, `PROT_EXEC` denoting updated access. Note access can only be removed, but not added back.

Returns

0 for success, -1 and sets errno on failure.