290 lines
9.9 KiB
C
290 lines
9.9 KiB
C
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
*
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
* http://www.mozilla.org/MPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
* for the specific language governing rights and limitations under the
|
|
* License.
|
|
*
|
|
* The Original Code is the Netscape Portable Runtime (NSPR).
|
|
*
|
|
* The Initial Developer of the Original Code is
|
|
* Netscape Communications Corporation.
|
|
* Portions created by the Initial Developer are Copyright (C) 1999-2000
|
|
* the Initial Developer. All Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
*
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
* either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
* the provisions above, a recipient may use your version of this file under
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
*
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
/*
|
|
** 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___ */
|