Back to index

lightning-sunbird  0.9+nobinonly
prshm.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1999-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039 ** prshm.h -- NSPR Shared Memory
00040 **
00041 ** NSPR Named Shared Memory API provides a cross-platform named
00042 ** shared-memory interface. NSPR Named Shared Memory is modeled on
00043 ** similar constructs in Unix and Windows operating systems. Shared
00044 ** memory allows multiple processes to access one or more common shared
00045 ** memory regions, using it as an inter-process communication channel.
00046 **
00047 ** Notes on Platform Independence:
00048 **   NSPR Named Shared Memory is built on the native services offered
00049 **   by most platforms. The NSPR Named Shared Memory API tries to
00050 **   provide a least common denominator interface so that it works
00051 **   across all supported platforms. To ensure that it works everywhere,
00052 **   some platform considerations must be accomodated and the protocol
00053 **   for using NSPR Shared Memory API must be observed.
00054 **
00055 ** Protocol:
00056 **   Multiple shared memories can be created using NSPR's Shared Memory
00057 **   feature. For each named shared memory, as defined by the name
00058 **   given in the PR_OpenSharedMemory() call, a protocol for using the
00059 **   shared memory API is required to ensure desired behavior. Failing
00060 **   to follow the protocol may yield unpredictable results.
00061 **   
00062 **   PR_OpenSharedMemory() will create the shared memory segment, if it
00063 **   does not already exist, or open a connection that the existing
00064 **   shared memory segment if it already exists.
00065 **   
00066 **   PR_AttachSharedMemory() should be called following
00067 **   PR_OpenSharedMemory() to map the memory segment to an address in
00068 **   the application's address space.
00069 **   
00070 **   PR_AttachSharedMemory() may be called to re-map a shared memory
00071 **   segment after detaching the same PRSharedMemory object. Be
00072 **   sure to detach it when done.
00073 **   
00074 **   PR_DetachSharedMemory() should be called to un-map the shared
00075 **   memory segment from the application's address space.
00076 **   
00077 **   PR_CloseSharedMemory() should be called when no further use of the
00078 **   PRSharedMemory object is required within a process. Following a
00079 **   call to  PR_CloseSharedMemory() the PRSharedMemory object is
00080 **   invalid and cannot be reused.
00081 **   
00082 **   PR_DeleteSharedMemory() should be called before process
00083 **   termination. After calling PR_DeleteSharedMemory() any further use
00084 **   of the shared memory associated with the name may cause
00085 **   unpredictable results.
00086 **   
00087 ** Files:
00088 **   The name passed to PR_OpenSharedMemory() should be a valid filename
00089 **   for a unix platform. PR_OpenSharedMemory() creates file using the
00090 **   name passed in. Some platforms may mangle the name before creating
00091 **   the file and the shared memory.
00092 **   
00093 **   The unix implementation may use SysV IPC shared memory, Posix
00094 **   shared memory, or memory mapped files; the filename may used to
00095 **   define the namespace. On Windows, the name is significant, but
00096 **   there is no file associated with name.
00097 **   
00098 **   No assumptions about the persistence of data in the named file
00099 **   should be made. Depending on platform, the shared memory may be
00100 **   mapped onto system paging space and be discarded at process
00101 **   termination.
00102 **   
00103 **   All names provided to PR_OpenSharedMemory() should be valid
00104 **   filename syntax or name syntax for shared memory for the target
00105 **   platform. Referenced directories should have permissions 
00106 **   appropriate for writing.
00107 **
00108 ** Limits:
00109 **   Different platforms have limits on both the number and size of
00110 **   shared memory resources. The default system limits on some
00111 **   platforms may be smaller than your requirements. These limits may
00112 **   be adjusted on some platforms either via boot-time options or by
00113 **   setting the size of the system paging space to accomodate more
00114 **   and/or larger shared memory segment(s).
00115 **
00116 ** Security:
00117 **   On unix platforms, depending on implementation, contents of the
00118 **   backing store for the shared memory can be exposed via the file
00119 **   system. Set permissions and or access controls at create and attach
00120 **   time to ensure you get the desired security.
00121 **
00122 **   On windows platforms, no special security measures are provided.
00123 **
00124 ** Example:
00125 **   The test case pr/tests/nameshm1.c provides an example of use as
00126 **   well as testing the operation of NSPR's Named Shared Memory.
00127 **
00128 ** lth. 18-Aug-1999.
00129 */
00130 
00131 #ifndef prshm_h___
00132 #define prshm_h___
00133 
00134 #include "prtypes.h"
00135 #include "prio.h"
00136 
00137 PR_BEGIN_EXTERN_C
00138 
00139 /*
00140 ** Declare opaque type PRSharedMemory.
00141 */
00142 typedef struct PRSharedMemory PRSharedMemory;
00143 
00144 /*
00145 ** FUNCTION: PR_OpenSharedMemory()
00146 **
00147 ** DESCRIPTION:
00148 **   PR_OpenSharedMemory() creates a new shared-memory segment or
00149 **   associates a previously created memory segment with name.
00150 **
00151 **   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
00152 **   shared memory already exists, the function returns NULL with the
00153 **   error set to PR_FILE_EXISTS_ERROR.
00154 **
00155 **   When parameter create is PR_SHM_CREATE and the shared memory
00156 **   already exists, a handle to that memory segment is returned. If
00157 **   the segment does not exist, it is created and a pointer to the
00158 **   related PRSharedMemory structure is returned.
00159 **
00160 **   When parameter create is 0, and the shared memory exists, a
00161 **   pointer to a PRSharedMemory is returned. If the shared memory does
00162 **   not exist, NULL is returned with the error set to
00163 **   PR_FILE_NOT_FOUND_ERROR.
00164 **
00165 ** INPUTS:
00166 **   name -- the name the shared-memory segment is known as.
00167 **   size -- the size of the shared memory segment. 
00168 **   flags -- Options for creating the shared memory
00169 **   mode -- Same as is passed to PR_Open()
00170 **
00171 ** OUTPUTS: 
00172 **   The shared memory is allocated.
00173 **
00174 ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
00175 **   NULL is returned on error. The reason for the error can be
00176 **   retrieved via PR_GetError() and PR_GetOSError();
00177 **
00178 */
00179 NSPR_API( PRSharedMemory * )
00180     PR_OpenSharedMemory(
00181         const char *name,
00182         PRSize      size,
00183         PRIntn      flags,
00184         PRIntn      mode
00185 );
00186 /* Define values for PR_OpenShareMemory(...,create) */
00187 #define PR_SHM_CREATE 0x1  /* create if not exist */
00188 #define PR_SHM_EXCL   0x2  /* fail if already exists */
00189 
00190 /*
00191 ** FUNCTION: PR_AttachSharedMemory()
00192 **
00193 ** DESCRIPTION:
00194 ** PR_AttachSharedMemory() maps the shared-memory described by
00195 ** shm to the current process. 
00196 **
00197 ** INPUTS: 
00198 **   shm -- The handle returned from PR_OpenSharedMemory().
00199 **   flags -- options for mapping the shared memory.
00200 **   PR_SHM_READONLY causes the memory to be attached 
00201 **   read-only.
00202 **
00203 ** OUTPUTS:
00204 **   On success, the shared memory segment represented by shm is mapped
00205 **   into the process' address space.
00206 **
00207 ** RETURNS: Address where shared memory is mapped, or NULL.
00208 **   NULL is returned on error. The reason for the error can be
00209 **   retrieved via PR_GetError() and PR_GetOSError();
00210 **
00211 **
00212 */
00213 NSPR_API( void * )
00214     PR_AttachSharedMemory(
00215         PRSharedMemory *shm,
00216         PRIntn  flags
00217 );
00218 /* Define values for PR_AttachSharedMemory(...,flags) */ 
00219 #define PR_SHM_READONLY 0x01
00220 
00221 /*
00222 ** FUNCTION: PR_DetachSharedMemory()
00223 **
00224 ** DESCRIPTION:
00225 **   PR_DetachSharedMemory() detaches the shared-memory described
00226 **   by shm. 
00227 **
00228 ** INPUTS: 
00229 **   shm -- The handle returned from PR_OpenSharedMemory().
00230 **   addr -- The address at which the memory was attached.
00231 **
00232 ** OUTPUTS:
00233 **   The shared memory mapped to an address via a previous call to
00234 **   PR_AttachSharedMemory() is unmapped.
00235 **
00236 ** RETURNS: PRStatus
00237 **
00238 */
00239 NSPR_API( PRStatus )
00240     PR_DetachSharedMemory(
00241         PRSharedMemory *shm,
00242         void  *addr
00243 );
00244 
00245 /*
00246 ** FUNCTION: PR_CloseSharedMemory()
00247 **
00248 ** DESCRIPTION:
00249 **   PR_CloseSharedMemory() closes the shared-memory described by
00250 **   shm.
00251 ** 
00252 ** INPUTS:
00253 **   shm -- The handle returned from PR_OpenSharedMemory().
00254 **
00255 ** OUTPUTS:
00256 **   the shared memory represented by shm is closed
00257 **
00258 ** RETURNS: PRStatus
00259 **
00260 */
00261 NSPR_API( PRStatus )
00262     PR_CloseSharedMemory(
00263         PRSharedMemory *shm
00264 );
00265 
00266 /*
00267 ** FUNCTION: PR_DeleteSharedMemory()
00268 **
00269 ** DESCRIPTION:
00270 **   The shared memory resource represented by name is released.
00271 **
00272 ** INPUTS:
00273 **   name -- the name the shared-memory segment
00274 **
00275 ** OUTPUTS:
00276 **   depending on platform, resources may be returned to the underlying
00277 **   operating system.
00278 **
00279 ** RETURNS: PRStatus
00280 **
00281 */
00282 NSPR_API( PRStatus )
00283     PR_DeleteSharedMemory( 
00284         const char *name
00285 );
00286 
00287 PR_END_EXTERN_C
00288 
00289 #endif /* prshm_h___ */