![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prshma.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / javascript / include / mozilla / nspr|
Return to prshma.h CVS log | Up to [Synchronet] / sbbs / javascript / 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: ** prshma.h -- NSPR Anonymous Shared Memory
37: **
38: ** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
39: ** type. The anonymous file-mapped shared memory provides an inheritable
40: ** shared memory, as in: the child process inherits the shared memory.
41: ** Compare the file-mapped anonymous shared memory to to a named shared
42: ** memory described in prshm.h. The intent is to provide a shared
43: ** memory that is accessable only by parent and child processes. ...
44: ** It's a security thing.
45: **
46: ** Depending on the underlying platform, the file-mapped shared memory
47: ** may be backed by a file. ... surprise! ... On some platforms, no
48: ** real file backs the shared memory. On platforms where the shared
49: ** memory is backed by a file, the file's name in the filesystem is
50: ** visible to other processes for only the duration of the creation of
51: ** the file, hopefully a very short time. This restricts processess
52: ** that do not inherit the shared memory from opening the file and
53: ** reading or writing its contents. Further, when all processes
54: ** using an anonymous shared memory terminate, the backing file is
55: ** deleted. ... If you are not paranoid, you're not paying attention.
56: **
57: ** The file-mapped shared memory requires a protocol for the parent
58: ** process and child process to share the memory. NSPR provides two
59: ** protocols. Use one or the other; don't mix and match.
60: **
61: ** In the first protocol, the job of passing the inheritable shared
62: ** memory is done via helper-functions with PR_CreateProcess(). In the
63: ** second protocol, the parent process is responsible for creating the
64: ** child process; the parent and child are mutually responsible for
65: ** passing a FileMap string. NSPR provides helper functions for
66: ** extracting data from the PRFileMap object. ... See the examples
67: ** below.
68: **
69: ** Both sides should adhere strictly to the protocol for proper
70: ** operation. The pseudo-code below shows the use of a file-mapped
71: ** shared memory by a parent and child processes. In the examples, the
72: ** server creates the file-mapped shared memory, the client attaches to
73: ** it.
74: **
75: ** First protocol.
76: ** Server:
77: **
78: ** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt);
79: ** addr = PR_MemMap(fm);
80: ** attr = PR_NewProcessAttr();
81: ** PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
82: ** PR_CreateProcess(Client);
83: ** PR_DestroyProcessAttr(attr);
84: ** ... yadda ...
85: ** PR_MemUnmap( addr );
86: ** PR_CloseFileMap(fm);
87: **
88: **
89: ** Client:
90: ** ... started by server via PR_CreateProcess()
91: ** fm = PR_GetInheritedFileMap( shmname );
92: ** addr = PR_MemMap(fm);
93: ** ... yadda ...
94: ** PR_MemUnmap(addr);
95: ** PR_CloseFileMap(fm);
96: **
97: **
98: ** Second Protocol:
99: ** Server:
100: **
101: ** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt);
102: ** fmstring = PR_ExportFileMapAsString( fm );
103: ** addr = PR_MemMap(fm);
104: ** ... application specific technique to pass fmstring to child
105: ** ... yadda ... Server uses his own magic to create child
106: ** PR_MemUnmap( addr );
107: ** PR_CloseFileMap(fm);
108: **
109: **
110: ** Client:
111: ** ... started by server via his own magic
112: ** ... application specific technique to find fmstring from parent
113: ** fm = PR_ImportFileMapFromString( fmstring )
114: ** addr = PR_MemMap(fm);
115: ** ... yadda ...
116: ** PR_MemUnmap(addr);
117: ** PR_CloseFileMap(fm);
118: **
119: **
120: ** lth. 2-Jul-1999.
121: **
122: ** Note: The second protocol was requested by NelsonB (7/1999); this is
123: ** to accomodate servers which already create their own child processes
124: ** using platform native methods.
125: **
126: */
127:
128: #ifndef prshma_h___
129: #define prshma_h___
130:
131: #include "prtypes.h"
132: #include "prio.h"
133: #include "prproces.h"
134:
135: PR_BEGIN_EXTERN_C
136:
137: /*
138: ** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
139: **
140: ** Description:
141: ** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
142: ** shared memory already exists, a handle is returned to that shared
143: ** memory object.
144: **
145: ** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
146: ** directory name, without the trailing '/', to contain the anonymous
147: ** file. A filename is generated for the name.
148: **
149: ** On Windows platforms, dirName is ignored.
150: **
151: ** Inputs:
152: ** dirName -- A directory name to contain the anonymous file.
153: ** size -- The size of the shared memory
154: ** prot -- How the shared memory is mapped. See prio.h
155: **
156: ** Outputs:
157: ** PRFileMap *
158: **
159: ** Returns:
160: ** Pointer to PRFileMap or NULL on error.
161: **
162: */
163: NSPR_API( PRFileMap *)
164: PR_OpenAnonFileMap(
165: const char *dirName,
166: PRSize size,
167: PRFileMapProtect prot
168: );
169:
170: /*
171: ** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export
172: ** to my children processes via PR_CreateProcess()
173: **
174: ** Description:
175: ** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
176: ** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
177: ** makes the PRFileMap importable by the child process.
178: **
179: ** Inputs:
180: ** attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
181: ** fm -- PRFileMap structure to be passed to the child process
182: ** shmname -- The name for the PRFileMap; used by child.
183: **
184: ** Outputs:
185: ** PRFileMap *
186: **
187: ** Returns:
188: ** PRStatus
189: **
190: */
191: NSPR_API(PRStatus)
192: PR_ProcessAttrSetInheritableFileMap(
193: PRProcessAttr *attr,
194: PRFileMap *fm,
195: const char *shmname
196: );
197:
198: /*
199: ** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
200: ** by my parent process via PR_CreateProcess()
201: **
202: ** Description:
203: ** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
204: ** its parent process via PR_CreateProcess().
205: **
206: ** Inputs:
207: ** shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
208: **
209: ** Outputs:
210: ** PRFileMap *
211: **
212: ** Returns:
213: ** PRFileMap pointer or NULL.
214: **
215: */
216: NSPR_API( PRFileMap *)
217: PR_GetInheritedFileMap(
218: const char *shmname
219: );
220:
221: /*
222: ** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
223: **
224: ** Description:
225: ** Creates an identifier, as a string, from a PRFileMap object
226: ** previously created with PR_OpenAnonFileMap().
227: **
228: ** Inputs:
229: ** fm -- PRFileMap pointer to be represented as a string.
230: ** bufsize -- sizeof(buf)
231: ** buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
232: **
233: ** Outputs:
234: ** buf contains the stringized PRFileMap identifier
235: **
236: ** Returns:
237: ** PRStatus
238: **
239: */
240: NSPR_API( PRStatus )
241: PR_ExportFileMapAsString(
242: PRFileMap *fm,
243: PRSize bufsize,
244: char *buf
245: );
246: #define PR_FILEMAP_STRING_BUFSIZE 128
247:
248: /*
249: ** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
250: **
251: ** Description:
252: ** PR_ImportFileMapFromString() creates a PRFileMap object from a
253: ** string previously created by PR_ExportFileMapAsString().
254: **
255: ** Inputs:
256: ** fmstring -- string created by PR_ExportFileMapAsString()
257: **
258: ** Returns:
259: ** PRFileMap pointer or NULL.
260: **
261: */
262: NSPR_API( PRFileMap * )
263: PR_ImportFileMapFromString(
264: const char *fmstring
265: );
266:
267: PR_END_EXTERN_C
268: #endif /* prshma_h___ */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.