/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
** prshm.h -- NSPR Shared Memory
**
** NSPR Named Shared Memory API provides a cross-platform named
** shared-memory interface. NSPR Named Shared Memory is modeled on
** similar constructs in Unix and Windows operating systems. Shared
** memory allows multiple processes to access one or more common shared
** memory regions, using it as an inter-process communication channel.
**
** Notes on Platform Independence:
**   NSPR Named Shared Memory is built on the native services offered
**   by most platforms. The NSPR Named Shared Memory API tries to
**   provide a least common denominator interface so that it works
**   across all supported platforms. To ensure that it works everywhere,
**   some platform considerations must be accomodated and the protocol
**   for using NSPR Shared Memory API must be observed.
**
** Protocol:
**   Multiple shared memories can be created using NSPR's Shared Memory
**   feature. For each named shared memory, as defined by the name
**   given in the PR_OpenSharedMemory() call, a protocol for using the
**   shared memory API is required to ensure desired behavior. Failing
**   to follow the protocol may yield unpredictable results.
**   
**   PR_OpenSharedMemory() will create the shared memory segment, if it
**   does not already exist, or open a connection that 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 be called to re-map a shared memory
**   segment after detaching the same PRSharedMemory object. Be
**   sure to detach it when done.
**   
**   PR_DetachSharedMemory() should be called to un-map 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 calling PR_DeleteSharedMemory() any further use
**   of the shared memory associated with the name may cause
**   unpredictable results.
**   
** Files:
**   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 used to
**   define the namespace. On Windows, the name is significant, but
**   there is no file associated with 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:
**   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 accomodate more
**   and/or larger shared memory segment(s).
**
** Security:
**   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.
**
** Example:
**   The test case pr/tests/nameshm1.c provides an example of use as
**   well as testing the operation of NSPR's Named Shared Memory.
**
** lth. 18-Aug-1999.
*/

#ifndef prshm_h___
#define prshm_h___

#include "prtypes.h"
#include "prio.h"

PR_BEGIN_EXTERN_C

/*
** Declare opaque type PRSharedMemory.
*/
typedef struct PRSharedMemory PRSharedMemory;

/*
** FUNCTION: PR_OpenSharedMemory()
**
** DESCRIPTION:
**   PR_OpenSharedMemory() creates a new shared-memory segment or
**   associates a previously created memory segment with 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 is returned. If the shared memory does
**   not exist, NULL is returned with the error set to
**   PR_FILE_NOT_FOUND_ERROR.
**
** INPUTS:
**   name -- the name the shared-memory segment is known as.
**   size -- the size of the shared memory segment. 
**   flags -- Options for creating the shared memory
**   mode -- Same as is passed to PR_Open()
**
** OUTPUTS: 
**   The shared memory is allocated.
**
** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
**   NULL is returned on error. The reason for the error can be
**   retrieved via PR_GetError() and PR_GetOSError();
**
*/
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 */

/*
** FUNCTION: PR_AttachSharedMemory()
**
** DESCRIPTION:
** PR_AttachSharedMemory() maps the shared-memory described by
** shm to the current process. 
**
** INPUTS: 
**   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.
**
** OUTPUTS:
**   On success, the shared memory segment represented by shm is mapped
**   into the process' address space.
**
** RETURNS: Address where shared memory is mapped, or NULL.
**   NULL is returned on error. The reason for the error can be
**   retrieved via PR_GetError() and PR_GetOSError();
**
**
*/
NSPR_API( void * )
    PR_AttachSharedMemory(
        PRSharedMemory *shm,
        PRIntn  flags
);
/* Define values for PR_AttachSharedMemory(...,flags) */ 
#define PR_SHM_READONLY 0x01

/*
** FUNCTION: PR_DetachSharedMemory()
**
** DESCRIPTION:
**   PR_DetachSharedMemory() detaches the shared-memory described
**   by shm. 
**
** INPUTS: 
**   shm -- The handle returned from PR_OpenSharedMemory().
**   addr -- The address at which the memory was attached.
**
** OUTPUTS:
**   The shared memory mapped to an address via a previous call to
**   PR_AttachSharedMemory() is unmapped.
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_DetachSharedMemory(
        PRSharedMemory *shm,
        void  *addr
);

/*
** FUNCTION: PR_CloseSharedMemory()
**
** DESCRIPTION:
**   PR_CloseSharedMemory() closes the shared-memory described by
**   shm.
** 
** INPUTS:
**   shm -- The handle returned from PR_OpenSharedMemory().
**
** OUTPUTS:
**   the shared memory represented by shm is closed
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_CloseSharedMemory(
        PRSharedMemory *shm
);

/*
** FUNCTION: PR_DeleteSharedMemory()
**
** DESCRIPTION:
**   The shared memory resource represented by name is released.
**
** INPUTS:
**   name -- the name the shared-memory segment
**
** OUTPUTS:
**   depending on platform, resources may be returned to the underlying
**   operating system.
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_DeleteSharedMemory( 
        const char *name
);

PR_END_EXTERN_C

#endif /* prshm_h___ */