NSPR Reference: Chapter 29 Anonymous Shared Memory
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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