Line data Source code
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 0 : 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 0 : 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 0 : 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 0 : 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 0 : PR_DeleteSharedMemory(
252 : const char *name
253 : );
254 :
255 : PR_END_EXTERN_C
256 :
257 : #endif /* prshm_h___ */
|
