![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prshm.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / include / mozilla / nspr|
Return to prshm.h CVS log | Up to [Synchronet] / sbbs / include / mozilla / nspr |
1.1 root 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:
134: PR_BEGIN_EXTERN_C
135:
136: /*
137: ** Declare opaque type PRSharedMemory.
138: */
139: typedef 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: */
176: NSPR_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: */
210: NSPR_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: */
236: NSPR_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: */
258: NSPR_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: */
279: NSPR_API( PRStatus )
280: PR_DeleteSharedMemory(
281: const char *name
282: );
283:
284: PR_END_EXTERN_C
285:
286: #endif /* prshm_h___ */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.