nsprpub/pr/include/prshm.h

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