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
105PR_BEGIN_EXTERN_C
106
107/*
108** Declare opaque type PRSharedMemory.
109*/
110typedef 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*/
147NSPR_API( PRSharedMemory * )
148PR_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*/
181NSPR_API( void * )
182PR_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*/
207NSPR_API( PRStatus )
208PR_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*/
229NSPR_API( PRStatus )
230PR_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*/
250NSPR_API( PRStatus )
251PR_DeleteSharedMemory(
252 const char *name
253);
254
255PR_END_EXTERN_C
256
257#endif /* prshm_h___ */
258

source code of include/nspr/prshm.h