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