You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 29   Anonymous Shared Memory

This chapter describes the NSPR API for anonymous shared memory.
<<work in progress, not yet edited>>

Anonymous Memory Protocol

NSPR provides an anonymous shared memory based on NSPR's PRFileMap type. The anonymous file-mapped shared memory provides an inheritable shared memory, as in: the child process inherits the shared memory. Compare the file-mapped anonymous shared memory to to a named shared memory described in prshm.h. The intent is to provide a shared memory that is accessable only by parent and child processes. ... It's a security thing.

Depending on the underlying platform, the file-mapped shared memory may be backed by a file. ... surprise! ... On some platforms, no real file backs the shared memory. On platforms where the shared memory is backed by a file, the file's name in the filesystem is visible to other processes for only the duration of the creation of the file, hopefully a very short time. This restricts processess that do not inherit the shared memory from opening the file and reading or writing its contents. Further, when all processes using an anonymous shared memory terminate, the backing file is deleted. ... If you are not paranoid, you're not paying attention.

The file-mapped shared memory requires a protocol for the parent process and child process to share the memory. NSPR provides two protocols. Use one or the other; don't mix and match.

In the first protocol, the job of passing the inheritable shared memory is done via helper-functions with PR_CreateProcess. In the second protocol, the parent process is responsible for creating the child process; the parent and child are mutually responsible for passing a FileMap string. NSPR provides helper functions for extracting data from the PRFileMap object. ... See the examples below.

Both sides should adhere strictly to the protocol for proper operation. The pseudo-code below shows the use of a file-mapped shared memory by a parent and child processes. In the examples, the server creates the file-mapped shared memory, the client attaches to it.

First protocol

Server:

fm = PR_OpenAnonFileMap(dirName, size, FilemapProt);
addr = PR_MemMap(fm);
attr = PR_NewProcessAttr();
PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
PR_CreateProcess(Client);
PR_DestroyProcessAttr(attr);
... yadda ...
PR_MemUnmap( addr );
PR_CloseFileMap(fm);

Client:

... started by server via PR_CreateProcess()
fm = PR_GetInheritedFileMap( shmname );
addr = PR_MemMap(fm);
... yadda ...
PR_MemUnmap(addr);
PR_CloseFileMap(fm);

Second Protocol

Server: 

fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
fmstring = PR_ExportFileMapAsString( fm );
addr = PR_MemMap(fm); 
... application specific technique to pass fmstring to child
... yadda ... Server uses his own magic to create child
PR_MemUnmap( addr );
PR_CloseFileMap(fm);

Client: 

... started by server via his own magic
... application specific technique to find fmstring from parent
fm = PR_ImportFileMapFromString( fmstring )
addr = PR_MemMap(fm);
... yadda ...
PR_MemUnmap(addr);
PR_CloseFileMap(fm);

Anonymous Shared Memory Functions

PR_OpenAnonFileMap
PR_ProcessAttrSetInheritableFileMap
PR_GetInheritedFileMap
PR_ExportFileMapAsString
PR_ImportFileMapFromString

PR_OpenAnonFileMap

Creates an anonymous file-mapped shared memory.


Syntax 
#include <prshma.h>


NSPR_API( PRFileMap *)
PR_OpenAnonFileMap(
   const char *dirName,
   PRSize size, 
   PRFileMapProtect prot
);


Parameters
The function has the following parameters: 

dirName

A pointer to a directory name that will contain the anonymous file. 

size

The size of the shared memory. 

prot

How the shared memory is mapped.


Returns
Pointer to PRFileMap or NULL on error.


Description
If the shared memory already exists, a handle is returned to that shared memory object.

On Unix platforms, PR_OpenAnonFileMap uses dirName as a directory name, without the trailing '/', to contain the anonymous file. A filename is generated for the name.

On Windows platforms, dirName is ignored.

PR_ProcessAttrSetInheritableFileMap

Prepare filemap for export to my children processes via PR_CreateProcess.


Syntax 
#include <prshma.h>


NSPR_API(PRStatus) 
PR_ProcessAttrSetInheritableFileMap( 
   PRProcessAttr   *attr,
   PRFileMap       *fm, 
   const char      *shmname
);


Parameters
The function has the following parameters: 

attr

Pointer to a PRProcessAttr structure used to pass data to PR_CreateProcess. 

fm

Pointer to a PRFileMap structure to be passed to the child process. 

shmname

Pointer to the name for the PRFileMap; used by child.


Returns
PRStatus


Description
PR_ProcessAttrSetInheritableFileMap connects the PRFileMap to PRProcessAttr with shmname. A subsequent call to PR_CreateProcess makes the PRFileMap importable by the child process.

Note: This function is not implemented.

PR_GetInheritedFileMap

Imports a PRFileMap previously exported by my parent process via PR_CreateProcess


Syntax
#include <prshma.h>

NSPR_API( PRFileMap *)
PR_GetInheritedFileMap(
   const char *shmname
);


Parameters
The function has the following parameter: 

shmname

The name provided to PR_ProcessAttrSetInheritableFileMap.


Returns
Pointer to PRFileMap or NULL on error.


Description
PR_GetInheritedFileMap retrieves a PRFileMap object exported from its parent process via PR_CreateProcess.

Note: This function is not implemented.

PR_ExportFileMapAsString

Creates a string identifying a PRFileMap.


Syntax
#include <prshma.h>

NSPR_API( PRStatus )
PR_ExportFileMapAsString(
   PRFileMap *fm,
   PRSize bufsize,
   char *buf
);

#define PR_FILEMAP_STRING_BUFSIZE 128


Parameters
The function has the following parameters: 

fm

A pointer to the PRFileMap to be represented as a string. 

bufsize

sizeof(buf) 

buf

A pointer to abuffer of length PR_FILEMAP_STRING_BUFSIZE.


Returns
PRStatus


Description
Creates an identifier, as a string, from a PRFileMap object previously created with PR_OpenAnonFileMap.

PR_ImportFileMapFromString

Creates a PRFileMap from an identifying string


Syntax 
#include <prshma.h>


NSPR_API( PRFileMap * )
PR_ImportFileMapFromString( 
   const char *fmstring
);


Parameters
The function has the following parameter: 

fmstring

A pointer to string created by PR_ExportFileMapAsString.


Returns
PRFileMap pointer or NULL on error.


Description
PR_ImportFileMapFromString creates a PRFileMap object from a string previously created by PR_ExportFileMapAsString.

Previous     Contents     Next     

Last Updated May 18, 2001