NSPR Reference: Chapter 28 Named 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 28 Named Shared Memory

The chapter describes the NSPR API for named shared memory. Shared memory allows multiple processes to access one or more common shared memory regions, using it as an interprocess communication channel. The NSPR shared memory API provides a cross-platform named shared-memory interface that is modeled on similar constructs in the Unix and Windows operating systems.

Shared Memory Protocol
Named Shared Memory Functions

## Shared Memory Protocol

Multiple shared memories can be created using the NSPR shared memory API. Each named shared memory segment defined by the `PR_OpenSharedMemory` call should be manipulated according to the protocol described here. Failing to follow the protocol may yield unpredictable results.

Using Named Shared Memory Functions
Filenames
Limits on Shared Memory Resources
Security Considerations

### Using Named Shared Memory Functions

`PR_OpenSharedMemory` creates the shared memory segment, if it does not already exist, or opens a connection with the existing shared memory segment if it already exists.

`PR_AttachSharedMemory` should be called following `PR_OpenSharedMemory` to map the memory segment to an address in the application's address space. `PR_AttachSharedMemory` may also be called to remap a shared memory segment after detaching the same `PRSharedMemory` object. Be sure to detach it when you're finished.

`PR_DetachSharedMemory` should be called to unmap the shared memory segment from the application's address space.

`PR_CloseSharedMemory` should be called when no further use of the `PRSharedMemory` object is required within a process. Following a call to `PR_CloseSharedMemory`, the `PRSharedMemory` object is invalid and cannot be reused.

`PR_DeleteSharedMemory` should be called before process termination. After you call `PR_DeleteSharedMemory`, any further use of the shared memory associated with the name may cause unpredictable results.

### Filenames

The name passed to `PR_OpenSharedMemory` should be a valid filename for a Unix platform. `PR_OpenSharedMemory` creates file using the name passed in. Some platforms may mangle the name before creating the file and the shared memory. The Unix implementation may use SysV IPC shared memory, Posix shared memory, or memory mapped files; the filename may be used to define the namespace. On Windows, the name is significant, but there is no file associated with the name.

No assumptions about the persistence of data in the named file should be made. Depending on platform, the shared memory may be mapped onto system paging space and be discarded at process termination.

All names provided to `PR_OpenSharedMemory` should be valid filename syntax or name syntax for shared memory for the target platform. Referenced directories should have permissions appropriate for writing.

### Limits on Shared Memory Resources

Different platforms have limits on both the number and size of shared memory resources. The default system limits on some platforms may be smaller than your requirements. These limits may be adjusted on some platforms either via boot-time options or by setting the size of the system paging space to accommodate more and/or larger shared memory segment(s).

### Security Considerations

On Unix platforms, depending on implementation, contents of the backing store for the shared memory can be exposed via the file system. Set permissions and or access controls at create and attach time to ensure you get the desired security.

On Windows platforms, no special security measures are provided.

## Named Shared Memory Functions

`PR_OpenSharedMemory`
`PR_AttachSharedMemory`
`PR_DetachSharedMemory`
`PR_CloseSharedMemory`
`PR_DeleteSharedMemory`

#### PR_OpenSharedMemory

Opens an existing shared memory segment or, if one with the specified name doesn't exist, creates a new one.

##### Syntax

    #include <prshm.h>

    NSPR_API( PRSharedMemory * )
       PR_OpenSharedMemory(
          const char             *name,
          PRSize             size,
          PRIntn             flags,
          PRIntn             mode
    );

    /* Define values for PR_OpenShareMemory(...,create) */
    #define PR_SHM_CREATE 0x1  /* create if not exist */
    #define PR_SHM_EXCL   0x2  /* fail if already exists */

##### Parameters

The function has the following parameters:

    name
| The name of the shared memory segment.
    size
| The size of the shared memory segment.
    flags
| Options for creating the shared memory.
    mode
| Same as passed to `PR_Open`.

##### Returns

Pointer to opaque structure `PRSharedMemory`, or `NULL` if an error occurs. Retrieve the reason for the failure by calling `PR_GetError` and `PR_GetOSError`.

##### Description

`PR_OpenSharedMemory` creates a new shared memory segment or associates a previously created memory segment with the specified name. When parameter `create` is `(PR_SHM_EXCL | PR_SHM_CREATE)` and the shared memory already exists, the function returns `NULL` with the error set to `PR_FILE_EXISTS_ERROR`.

When parameter `create` is `PR_SHM_CREATE` and the shared memory already exists, a handle to that memory segment is returned. If the segment does not exist, it is created and a pointer to the related `PRSharedMemory` structure is returned.

When parameter `create` is 0, and the shared memory exists, a pointer to a `PRSharedMemory`structure is returned. If the shared memory does not exist, `NULL` is returned with the error set to `PR_FILE_NOT_FOUND_ERROR`.

#### PR_AttachSharedMemory

Attaches a memory segment previously opened with `PR_OpenSharedMemory` and maps it into the process memory space.

##### Syntax

`#include <prshm.h>`

`NSPR_API( void * )
PR_AttachSharedMemory(
PRSharedMemory *shm,
PRIntn flags
);`

`/* Define values for PR_AttachSharedMemory(...,flags) */
#define PR_SHM_READONLY 0x01`

##### Parameters

The function has these parameters:

    shm
| The handle returned from `PR_OpenSharedMemory`.
    flags
| Options for mapping the shared memory. `PR_SHM_READONLY` causes the memory to be attached read-only.

##### Returns

Address where shared memory is mapped, or `NULL` if an error occurs. Retrieve the reason for the failure by calling `PR_GetError` and `PR_GetOSError`.

#### PR_DetachSharedMemory

Unmaps a shared memory segment identified by name.

##### Syntax

    #include <prshm.h>

    NSPR_API( PRStatus )
       PR_DetachSharedMemory(
          PRSharedMemory *shm,
          void  *addr
    );

##### Parameters

The function has these parameters:

    shm
| The handle returned from `PR_OpenSharedMemory`.
    addr
| The address to which the shared memory segment is mapped.

##### Returns

`PRStatus`.

#### PR_CloseSharedMemory

Closes a shared memory segment identified by name.

##### Syntax

    #include <prshm.h>

    NSPR_API( PRStatus )
       PR_CloseSharedMemory(
          PRSharedMemory *shm
    );

##### Parameters

The function has this parameter:

    shm
| The handle returned from `PR_OpenSharedMemory`.

##### Returns

`PRStatus`.

#### PR_DeleteSharedMemory

Deletes a shared memory segment identified by name.

##### Syntax

    #include <prshm.h>

    NSPR_API( PRStatus )
       PR_DeleteSharedMemory(
          const char *name
    );

##### Parameters

The function has this parameter:

    shm
| The handle returned from `PR_OpenSharedMemory`.

##### Returns

`PRStatus`.

Previous Contents Next

Last Updated May 18, 2001