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