nsprpub/pr/include/prshm.h

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