Memory

#include <sharedmem.h>
#include <sharedmem_jni.h>

Summary

Functions

ASharedMemory_create(const char *name, size_t size)
int
Structures and functions for a shared memory buffer that can be shared across process.
ASharedMemory_dupFromJava(JNIEnv *env, jobject sharedMemory)
int
Structures and functions for a shared memory buffer that can be shared across process.
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

int ASharedMemory_create(
  const char *name,
  size_t size
)

Structures and functions for a shared memory buffer that can be shared across process.

Create a shared memory region.

Create shared memory region and returns an file descriptor. The resulting file descriptor can be mmap'ed to process memory space with PROT_READ | PROT_WRITE | PROT_EXEC. Access to shared memory region can be restricted with ASharedMemory_setProt.

Use close() to release the shared memory region.

Details
Parameters
name
an optional name.
size
size of the shared memory region
Returns
file descriptor that denotes the shared memory; error code on failure.

ASharedMemory_dupFromJava

int ASharedMemory_dupFromJava(
  JNIEnv *env,
  jobject sharedMemory
)

Structures and functions for a shared memory buffer that can be shared across process.

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.

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

size_t ASharedMemory_getSize(
  int fd
)

Get the size of the shared memory region.

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

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.
char *buffer = (char *) mmap(NULL, 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.

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, error code on failure.