The Tor Browser / file comparison

comparison: nsprpub/pr/include/prshma.h

nsprpub/pr/include/prshma.h

branch
TOR_BUG_9701
changeset 13
44a2da4a2ab2
equal deleted inserted replaced
-1:000000000000 0:d3cb2ba6b436
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 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 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 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 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 PR_ImportFileMapFromString(
235 const char *fmstring
236 );
237
238 PR_END_EXTERN_C
239 #endif /* prshma_h___ */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial