1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 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/
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.
13 * The Original Code is the Netscape Portable Runtime (NSPR).
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
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
36 ** prshm.h -- NSPR Shared Memory
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.
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.
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.
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.
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.
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.
71 ** PR_DetachSharedMemory() should be called to un-map the shared
72 ** memory segment from the application's address space.
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.
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.
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.
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.
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
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.
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).
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.
119 ** On windows platforms, no special security measures are provided.
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.
137 ** Declare opaque type PRSharedMemory.
139 typedef struct PRSharedMemory PRSharedMemory;
142 ** FUNCTION: PR_OpenSharedMemory()
145 ** PR_OpenSharedMemory() creates a new shared-memory segment or
146 ** associates a previously created memory segment with name.
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.
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.
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.
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()
169 ** The shared memory is allocated.
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();
176 NSPR_API( PRSharedMemory * )
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 */
188 ** FUNCTION: PR_AttachSharedMemory()
191 ** PR_AttachSharedMemory() maps the shared-memory described by
192 ** shm to the current process.
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
201 ** On success, the shared memory segment represented by shm is mapped
202 ** into the process' address space.
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();
211 PR_AttachSharedMemory(
215 /* Define values for PR_AttachSharedMemory(...,flags) */
216 #define PR_SHM_READONLY 0x01
219 ** FUNCTION: PR_DetachSharedMemory()
222 ** PR_DetachSharedMemory() detaches the shared-memory described
226 ** shm -- The handle returned from PR_OpenSharedMemory().
227 ** addr -- The address at which the memory was attached.
230 ** The shared memory mapped to an address via a previous call to
231 ** PR_AttachSharedMemory() is unmapped.
237 PR_DetachSharedMemory(
243 ** FUNCTION: PR_CloseSharedMemory()
246 ** PR_CloseSharedMemory() closes the shared-memory described by
250 ** shm -- The handle returned from PR_OpenSharedMemory().
253 ** the shared memory represented by shm is closed
259 PR_CloseSharedMemory(
264 ** FUNCTION: PR_DeleteSharedMemory()
267 ** The shared memory resource represented by name is released.
270 ** name -- the name the shared-memory segment
273 ** depending on platform, resources may be returned to the underlying
280 PR_DeleteSharedMemory(
286 #endif /* prshm_h___ */