michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /*
michael@0: ** prshm.h -- NSPR Shared Memory
michael@0: **
michael@0: ** NSPR Named Shared Memory API provides a cross-platform named
michael@0: ** shared-memory interface. NSPR Named Shared Memory is modeled on
michael@0: ** similar constructs in Unix and Windows operating systems. Shared
michael@0: ** memory allows multiple processes to access one or more common shared
michael@0: ** memory regions, using it as an inter-process communication channel.
michael@0: **
michael@0: ** Notes on Platform Independence:
michael@0: **   NSPR Named Shared Memory is built on the native services offered
michael@0: **   by most platforms. The NSPR Named Shared Memory API tries to
michael@0: **   provide a least common denominator interface so that it works
michael@0: **   across all supported platforms. To ensure that it works everywhere,
michael@0: **   some platform considerations must be accomodated and the protocol
michael@0: **   for using NSPR Shared Memory API must be observed.
michael@0: **
michael@0: ** Protocol:
michael@0: **   Multiple shared memories can be created using NSPR's Shared Memory
michael@0: **   feature. For each named shared memory, as defined by the name
michael@0: **   given in the PR_OpenSharedMemory() call, a protocol for using the
michael@0: **   shared memory API is required to ensure desired behavior. Failing
michael@0: **   to follow the protocol may yield unpredictable results.
michael@0: **   
michael@0: **   PR_OpenSharedMemory() will create the shared memory segment, if it
michael@0: **   does not already exist, or open a connection that the existing
michael@0: **   shared memory segment if it already exists.
michael@0: **   
michael@0: **   PR_AttachSharedMemory() should be called following
michael@0: **   PR_OpenSharedMemory() to map the memory segment to an address in
michael@0: **   the application's address space.
michael@0: **   
michael@0: **   PR_AttachSharedMemory() may be called to re-map a shared memory
michael@0: **   segment after detaching the same PRSharedMemory object. Be
michael@0: **   sure to detach it when done.
michael@0: **   
michael@0: **   PR_DetachSharedMemory() should be called to un-map the shared
michael@0: **   memory segment from the application's address space.
michael@0: **   
michael@0: **   PR_CloseSharedMemory() should be called when no further use of the
michael@0: **   PRSharedMemory object is required within a process. Following a
michael@0: **   call to  PR_CloseSharedMemory() the PRSharedMemory object is
michael@0: **   invalid and cannot be reused.
michael@0: **   
michael@0: **   PR_DeleteSharedMemory() should be called before process
michael@0: **   termination. After calling PR_DeleteSharedMemory() any further use
michael@0: **   of the shared memory associated with the name may cause
michael@0: **   unpredictable results.
michael@0: **   
michael@0: ** Files:
michael@0: **   The name passed to PR_OpenSharedMemory() should be a valid filename
michael@0: **   for a unix platform. PR_OpenSharedMemory() creates file using the
michael@0: **   name passed in. Some platforms may mangle the name before creating
michael@0: **   the file and the shared memory.
michael@0: **   
michael@0: **   The unix implementation may use SysV IPC shared memory, Posix
michael@0: **   shared memory, or memory mapped files; the filename may used to
michael@0: **   define the namespace. On Windows, the name is significant, but
michael@0: **   there is no file associated with name.
michael@0: **   
michael@0: **   No assumptions about the persistence of data in the named file
michael@0: **   should be made. Depending on platform, the shared memory may be
michael@0: **   mapped onto system paging space and be discarded at process
michael@0: **   termination.
michael@0: **   
michael@0: **   All names provided to PR_OpenSharedMemory() should be valid
michael@0: **   filename syntax or name syntax for shared memory for the target
michael@0: **   platform. Referenced directories should have permissions 
michael@0: **   appropriate for writing.
michael@0: **
michael@0: ** Limits:
michael@0: **   Different platforms have limits on both the number and size of
michael@0: **   shared memory resources. The default system limits on some
michael@0: **   platforms may be smaller than your requirements. These limits may
michael@0: **   be adjusted on some platforms either via boot-time options or by
michael@0: **   setting the size of the system paging space to accomodate more
michael@0: **   and/or larger shared memory segment(s).
michael@0: **
michael@0: ** Security:
michael@0: **   On unix platforms, depending on implementation, contents of the
michael@0: **   backing store for the shared memory can be exposed via the file
michael@0: **   system. Set permissions and or access controls at create and attach
michael@0: **   time to ensure you get the desired security.
michael@0: **
michael@0: **   On windows platforms, no special security measures are provided.
michael@0: **
michael@0: ** Example:
michael@0: **   The test case pr/tests/nameshm1.c provides an example of use as
michael@0: **   well as testing the operation of NSPR's Named Shared Memory.
michael@0: **
michael@0: ** lth. 18-Aug-1999.
michael@0: */
michael@0: 
michael@0: #ifndef prshm_h___
michael@0: #define prshm_h___
michael@0: 
michael@0: #include "prtypes.h"
michael@0: #include "prio.h"
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: 
michael@0: /*
michael@0: ** Declare opaque type PRSharedMemory.
michael@0: */
michael@0: typedef struct PRSharedMemory PRSharedMemory;
michael@0: 
michael@0: /*
michael@0: ** FUNCTION: PR_OpenSharedMemory()
michael@0: **
michael@0: ** DESCRIPTION:
michael@0: **   PR_OpenSharedMemory() creates a new shared-memory segment or
michael@0: **   associates a previously created memory segment with name.
michael@0: **
michael@0: **   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
michael@0: **   shared memory already exists, the function returns NULL with the
michael@0: **   error set to PR_FILE_EXISTS_ERROR.
michael@0: **
michael@0: **   When parameter create is PR_SHM_CREATE and the shared memory
michael@0: **   already exists, a handle to that memory segment is returned. If
michael@0: **   the segment does not exist, it is created and a pointer to the
michael@0: **   related PRSharedMemory structure is returned.
michael@0: **
michael@0: **   When parameter create is 0, and the shared memory exists, a
michael@0: **   pointer to a PRSharedMemory is returned. If the shared memory does
michael@0: **   not exist, NULL is returned with the error set to
michael@0: **   PR_FILE_NOT_FOUND_ERROR.
michael@0: **
michael@0: ** INPUTS:
michael@0: **   name -- the name the shared-memory segment is known as.
michael@0: **   size -- the size of the shared memory segment. 
michael@0: **   flags -- Options for creating the shared memory
michael@0: **   mode -- Same as is passed to PR_Open()
michael@0: **
michael@0: ** OUTPUTS: 
michael@0: **   The shared memory is allocated.
michael@0: **
michael@0: ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
michael@0: **   NULL is returned on error. The reason for the error can be
michael@0: **   retrieved via PR_GetError() and PR_GetOSError();
michael@0: **
michael@0: */
michael@0: NSPR_API( PRSharedMemory * )
michael@0:     PR_OpenSharedMemory(
michael@0:         const char *name,
michael@0:         PRSize      size,
michael@0:         PRIntn      flags,
michael@0:         PRIntn      mode
michael@0: );
michael@0: /* Define values for PR_OpenShareMemory(...,create) */
michael@0: #define PR_SHM_CREATE 0x1  /* create if not exist */
michael@0: #define PR_SHM_EXCL   0x2  /* fail if already exists */
michael@0: 
michael@0: /*
michael@0: ** FUNCTION: PR_AttachSharedMemory()
michael@0: **
michael@0: ** DESCRIPTION:
michael@0: ** PR_AttachSharedMemory() maps the shared-memory described by
michael@0: ** shm to the current process. 
michael@0: **
michael@0: ** INPUTS: 
michael@0: **   shm -- The handle returned from PR_OpenSharedMemory().
michael@0: **   flags -- options for mapping the shared memory.
michael@0: **   PR_SHM_READONLY causes the memory to be attached 
michael@0: **   read-only.
michael@0: **
michael@0: ** OUTPUTS:
michael@0: **   On success, the shared memory segment represented by shm is mapped
michael@0: **   into the process' address space.
michael@0: **
michael@0: ** RETURNS: Address where shared memory is mapped, or NULL.
michael@0: **   NULL is returned on error. The reason for the error can be
michael@0: **   retrieved via PR_GetError() and PR_GetOSError();
michael@0: **
michael@0: **
michael@0: */
michael@0: NSPR_API( void * )
michael@0:     PR_AttachSharedMemory(
michael@0:         PRSharedMemory *shm,
michael@0:         PRIntn  flags
michael@0: );
michael@0: /* Define values for PR_AttachSharedMemory(...,flags) */ 
michael@0: #define PR_SHM_READONLY 0x01
michael@0: 
michael@0: /*
michael@0: ** FUNCTION: PR_DetachSharedMemory()
michael@0: **
michael@0: ** DESCRIPTION:
michael@0: **   PR_DetachSharedMemory() detaches the shared-memory described
michael@0: **   by shm. 
michael@0: **
michael@0: ** INPUTS: 
michael@0: **   shm -- The handle returned from PR_OpenSharedMemory().
michael@0: **   addr -- The address at which the memory was attached.
michael@0: **
michael@0: ** OUTPUTS:
michael@0: **   The shared memory mapped to an address via a previous call to
michael@0: **   PR_AttachSharedMemory() is unmapped.
michael@0: **
michael@0: ** RETURNS: PRStatus
michael@0: **
michael@0: */
michael@0: NSPR_API( PRStatus )
michael@0:     PR_DetachSharedMemory(
michael@0:         PRSharedMemory *shm,
michael@0:         void  *addr
michael@0: );
michael@0: 
michael@0: /*
michael@0: ** FUNCTION: PR_CloseSharedMemory()
michael@0: **
michael@0: ** DESCRIPTION:
michael@0: **   PR_CloseSharedMemory() closes the shared-memory described by
michael@0: **   shm.
michael@0: ** 
michael@0: ** INPUTS:
michael@0: **   shm -- The handle returned from PR_OpenSharedMemory().
michael@0: **
michael@0: ** OUTPUTS:
michael@0: **   the shared memory represented by shm is closed
michael@0: **
michael@0: ** RETURNS: PRStatus
michael@0: **
michael@0: */
michael@0: NSPR_API( PRStatus )
michael@0:     PR_CloseSharedMemory(
michael@0:         PRSharedMemory *shm
michael@0: );
michael@0: 
michael@0: /*
michael@0: ** FUNCTION: PR_DeleteSharedMemory()
michael@0: **
michael@0: ** DESCRIPTION:
michael@0: **   The shared memory resource represented by name is released.
michael@0: **
michael@0: ** INPUTS:
michael@0: **   name -- the name the shared-memory segment
michael@0: **
michael@0: ** OUTPUTS:
michael@0: **   depending on platform, resources may be returned to the underlying
michael@0: **   operating system.
michael@0: **
michael@0: ** RETURNS: PRStatus
michael@0: **
michael@0: */
michael@0: NSPR_API( PRStatus )
michael@0:     PR_DeleteSharedMemory( 
michael@0:         const char *name
michael@0: );
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* prshm_h___ */