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