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___ */ 287
