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 134PR_BEGIN_EXTERN_C 135 136/* 137** Declare opaque type PRSharedMemory. 138*/ 139typedef 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*/ 176NSPR_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*/ 210NSPR_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*/ 236NSPR_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*/ 258NSPR_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*/ 279NSPR_API( PRStatus ) 280 PR_DeleteSharedMemory( 281 const char *name 282); 283 284PR_END_EXTERN_C 285 286#endif /* prshm_h___ */ 287