src/third_party/npapi/npspy/extern/nspr/prshm.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /*
   3  * The contents of this file are subject to the Mozilla Public
   4  * License Version 1.1 (the "License"); you may not use this file
   5  * except in compliance with the License. You may obtain a copy of
   6  * the License at http://www.mozilla.org/MPL/
   7  *
   8  * Software distributed under the License is distributed on an "AS
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  10  * implied. See the License for the specific language governing
  11  * rights and limitations under the License.
  12  *
  13  * The Original Code is the Netscape Portable Runtime (NSPR).
  14  *
  15  * The Initial Developer of the Original Code is Netscape
  16  * Communications Corporation.  Portions created by Netscape are
  17  * Copyright (C) 1999-2000 Netscape Communications Corporation.  All
  18  * Rights Reserved.
  19  *
  20  * Contributor(s):
  21  *
  22  * Alternatively, the contents of this file may be used under the
  23  * terms of the GNU General Public License Version 2 or later (the
  24  * "GPL"), in which case the provisions of the GPL are applicable
  25  * instead of those above.  If you wish to allow use of your
  26  * version of this file only under the terms of the GPL and not to
  27  * allow others to use your version of this file under the MPL,
  28  * indicate your decision by deleting the provisions above and
  29  * replace them with the notice and other provisions required by
  30  * the GPL.  If you do not delete the provisions above, a recipient
  31  * may use your version of this file under either the MPL or the
  32  * GPL.
  33  */
  34
  35 /*
  36 ** prshm.h -- NSPR Shared Memory
  37 **
  38 ** NSPR Named Shared Memory API provides a cross-platform named
  39 ** shared-memory interface. NSPR Named Shared Memory is modeled on
  40 ** similar constructs in Unix and Windows operating systems. Shared
  41 ** memory allows multiple processes to access one or more common shared
  42 ** memory regions, using it as an inter-process communication channel.
  43 **
  44 ** Notes on Platform Independence:
  45 **   NSPR Named Shared Memory is built on the native services offered
  46 **   by most platforms. The NSPR Named Shared Memory API tries to
  47 **   provide a least common denominator interface so that it works
  48 **   across all supported platforms. To ensure that it works everywhere,
  49 **   some platform considerations must be accomodated and the protocol
  50 **   for using NSPR Shared Memory API must be observed.
  51 **
  52 ** Protocol:
  53 **   Multiple shared memories can be created using NSPR's Shared Memory
  54 **   feature. For each named shared memory, as defined by the name
  55 **   given in the PR_OpenSharedMemory() call, a protocol for using the
  56 **   shared memory API is required to ensure desired behavior. Failing
  57 **   to follow the protocol may yield unpredictable results.
  58 **
  59 **   PR_OpenSharedMemory() will create the shared memory segment, if it
  60 **   does not already exist, or open a connection that the existing
  61 **   shared memory segment if it already exists.
  62 **
  63 **   PR_AttachSharedMemory() should be called following
  64 **   PR_OpenSharedMemory() to map the memory segment to an address in
  65 **   the application's address space.
  66 **
  67 **   PR_AttachSharedMemory() may be called to re-map a shared memory
  68 **   segment after detaching the same PRSharedMemory object. Be
  69 **   sure to detach it when done.
  70 **
  71 **   PR_DetachSharedMemory() should be called to un-map the shared
  72 **   memory segment from the application's address space.
  73 **
  74 **   PR_CloseSharedMemory() should be called when no further use of the
  75 **   PRSharedMemory object is required within a process. Following a
  76 **   call to  PR_CloseSharedMemory() the PRSharedMemory object is
  77 **   invalid and cannot be reused.
  78 **
  79 **   PR_DeleteSharedMemory() should be called before process
  80 **   termination. After calling PR_DeleteSharedMemory() any further use
  81 **   of the shared memory associated with the name may cause
  82 **   unpredictable results.
  83 **
  84 ** Files:
  85 **   The name passed to PR_OpenSharedMemory() should be a valid filename
  86 **   for a unix platform. PR_OpenSharedMemory() creates file using the
  87 **   name passed in. Some platforms may mangle the name before creating
  88 **   the file and the shared memory.
  89 **
  90 **   The unix implementation may use SysV IPC shared memory, Posix
  91 **   shared memory, or memory mapped files; the filename may used to
  92 **   define the namespace. On Windows, the name is significant, but
  93 **   there is no file associated with name.
  94 **
  95 **   No assumptions about the persistence of data in the named file
  96 **   should be made. Depending on platform, the shared memory may be
  97 **   mapped onto system paging space and be discarded at process
  98 **   termination.
  99 **
 100 **   All names provided to PR_OpenSharedMemory() should be valid
 101 **   filename syntax or name syntax for shared memory for the target
 102 **   platform. Referenced directories should have permissions
 103 **   appropriate for writing.
 104 **
 105 ** Limits:
 106 **   Different platforms have limits on both the number and size of
 107 **   shared memory resources. The default system limits on some
 108 **   platforms may be smaller than your requirements. These limits may
 109 **   be adjusted on some platforms either via boot-time options or by
 110 **   setting the size of the system paging space to accomodate more
 111 **   and/or larger shared memory segment(s).
 112 **
 113 ** Security:
 114 **   On unix platforms, depending on implementation, contents of the
 115 **   backing store for the shared memory can be exposed via the file
 116 **   system. Set permissions and or access controls at create and attach
 117 **   time to ensure you get the desired security.
 118 **
 119 **   On windows platforms, no special security measures are provided.
 120 **
 121 ** Example:
 122 **   The test case pr/tests/nameshm1.c provides an example of use as
 123 **   well as testing the operation of NSPR's Named Shared Memory.
 124 **
 125 ** lth. 18-Aug-1999.
 126 */
 127
 128 #ifndef prshm_h___
 129 #define prshm_h___
 130
 131 #include "prtypes.h"
 132 #include "prio.h"
 133
 134 PR_BEGIN_EXTERN_C
 135
 136 /*
 137 ** Declare opaque type PRSharedMemory.
 138 */
 139 typedef struct PRSharedMemory PRSharedMemory;
 140
 141 /*
 142 ** FUNCTION: PR_OpenSharedMemory()
 143 **
 144 ** DESCRIPTION:
 145 **   PR_OpenSharedMemory() creates a new shared-memory segment or
 146 **   associates a previously created memory segment with name.
 147 **
 148 **   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
 149 **   shared memory already exists, the function returns NULL with the
 150 **   error set to PR_FILE_EXISTS_ERROR.
 151 **
 152 **   When parameter create is PR_SHM_CREATE and the shared memory
 153 **   already exists, a handle to that memory segment is returned. If
 154 **   the segment does not exist, it is created and a pointer to the
 155 **   related PRSharedMemory structure is returned.
 156 **
 157 **   When parameter create is 0, and the shared memory exists, a
 158 **   pointer to a PRSharedMemory is returned. If the shared memory does
 159 **   not exist, NULL is returned with the error set to
 160 **   PR_FILE_NOT_FOUND_ERROR.
 161 **
 162 ** INPUTS:
 163 **   name -- the name the shared-memory segment is known as.
 164 **   size -- the size of the shared memory segment.
 165 **   flags -- Options for creating the shared memory
 166 **   mode -- Same as is passed to PR_Open()
 167 **
 168 ** OUTPUTS:
 169 **   The shared memory is allocated.
 170 **
 171 ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
 172 **   NULL is returned on error. The reason for the error can be
 173 **   retrieved via PR_GetError() and PR_GetOSError();
 174 **
 175 */
 176 NSPR_API( PRSharedMemory * )
 177     PR_OpenSharedMemory(
 178         const char *name,
 179         PRSize      size,
 180         PRIntn      flags,
 181         PRIntn      mode
 182 );
 183 /* Define values for PR_OpenShareMemory(...,create) */
 184 #define PR_SHM_CREATE 0x1  /* create if not exist */
 185 #define PR_SHM_EXCL   0x2  /* fail if already exists */
 186
 187 /*
 188 ** FUNCTION: PR_AttachSharedMemory()
 189 **
 190 ** DESCRIPTION:
 191 ** PR_AttachSharedMemory() maps the shared-memory described by
 192 ** shm to the current process.
 193 **
 194 ** INPUTS:
 195 **   shm -- The handle returned from PR_OpenSharedMemory().
 196 **   flags -- options for mapping the shared memory.
 197 **   PR_SHM_READONLY causes the memory to be attached
 198 **   read-only.
 199 **
 200 ** OUTPUTS:
 201 **   On success, the shared memory segment represented by shm is mapped
 202 **   into the process' address space.
 203 **
 204 ** RETURNS: Address where shared memory is mapped, or NULL.
 205 **   NULL is returned on error. The reason for the error can be
 206 **   retrieved via PR_GetError() and PR_GetOSError();
 207 **
 208 **
 209 */
 210 NSPR_API( void * )
 211     PR_AttachSharedMemory(
 212         PRSharedMemory *shm,
 213         PRIntn  flags
 214 );
 215 /* Define values for PR_AttachSharedMemory(...,flags) */
 216 #define PR_SHM_READONLY 0x01
 217
 218 /*
 219 ** FUNCTION: PR_DetachSharedMemory()
 220 **
 221 ** DESCRIPTION:
 222 **   PR_DetachSharedMemory() detaches the shared-memory described
 223 **   by shm.
 224 **
 225 ** INPUTS:
 226 **   shm -- The handle returned from PR_OpenSharedMemory().
 227 **   addr -- The address at which the memory was attached.
 228 **
 229 ** OUTPUTS:
 230 **   The shared memory mapped to an address via a previous call to
 231 **   PR_AttachSharedMemory() is unmapped.
 232 **
 233 ** RETURNS: PRStatus
 234 **
 235 */
 236 NSPR_API( PRStatus )
 237     PR_DetachSharedMemory(
 238         PRSharedMemory *shm,
 239         void  *addr
 240 );
 241
 242 /*
 243 ** FUNCTION: PR_CloseSharedMemory()
 244 **
 245 ** DESCRIPTION:
 246 **   PR_CloseSharedMemory() closes the shared-memory described by
 247 **   shm.
 248 **
 249 ** INPUTS:
 250 **   shm -- The handle returned from PR_OpenSharedMemory().
 251 **
 252 ** OUTPUTS:
 253 **   the shared memory represented by shm is closed
 254 **
 255 ** RETURNS: PRStatus
 256 **
 257 */
 258 NSPR_API( PRStatus )
 259     PR_CloseSharedMemory(
 260         PRSharedMemory *shm
 261 );
 262
 263 /*
 264 ** FUNCTION: PR_DeleteSharedMemory()
 265 **
 266 ** DESCRIPTION:
 267 **   The shared memory resource represented by name is released.
 268 **
 269 ** INPUTS:
 270 **   name -- the name the shared-memory segment
 271 **
 272 ** OUTPUTS:
 273 **   depending on platform, resources may be returned to the underlying
 274 **   operating system.
 275 **
 276 ** RETURNS: PRStatus
 277 **
 278 */
 279 NSPR_API( PRStatus )
 280     PR_DeleteSharedMemory(
 281         const char *name
 282 );
 283
 284 PR_END_EXTERN_C
 285
 286 #endif /* prshm_h___ */