PageRenderTime 103ms CodeModel.GetById 40ms app.highlight 4ms RepoModel.GetById 56ms app.codeStats 0ms

/gecko_api/include/prshma.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 271 lines | 35 code | 10 blank | 226 comment | 0 complexity | af20d9284b5131fc1fe1b64a6974a89b MD5 | raw file
  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is the Netscape Portable Runtime (NSPR).
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1999-2000
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either the GNU General Public License Version 2 or later (the "GPL"), or
 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38/*
 39** prshma.h -- NSPR Anonymous Shared Memory
 40**
 41** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
 42** type. The anonymous file-mapped shared memory provides an inheritable
 43** shared memory, as in: the child process inherits the shared memory.
 44** Compare the file-mapped anonymous shared memory to to a named shared
 45** memory described in prshm.h. The intent is to provide a shared
 46** memory that is accessable only by parent and child processes. ...
 47** It's a security thing.
 48** 
 49** Depending on the underlying platform, the file-mapped shared memory
 50** may be backed by a file. ... surprise! ... On some platforms, no
 51** real file backs the shared memory. On platforms where the shared
 52** memory is backed by a file, the file's name in the filesystem is
 53** visible to other processes for only the duration of the creation of
 54** the file, hopefully a very short time. This restricts processess
 55** that do not inherit the shared memory from opening the file and
 56** reading or writing its contents. Further, when all processes
 57** using an anonymous shared memory terminate, the backing file is
 58** deleted. ... If you are not paranoid, you're not paying attention.
 59** 
 60** The file-mapped shared memory requires a protocol for the parent
 61** process and child process to share the memory. NSPR provides two
 62** protocols. Use one or the other; don't mix and match.
 63** 
 64** In the first protocol, the job of passing the inheritable shared
 65** memory is done via helper-functions with PR_CreateProcess(). In the
 66** second protocol, the parent process is responsible for creating the
 67** child process; the parent and child are mutually responsible for
 68** passing a FileMap string. NSPR provides helper functions for
 69** extracting data from the PRFileMap object. ... See the examples
 70** below.
 71** 
 72** Both sides should adhere strictly to the protocol for proper
 73** operation. The pseudo-code below shows the use of a file-mapped
 74** shared memory by a parent and child processes. In the examples, the
 75** server creates the file-mapped shared memory, the client attaches to
 76** it.
 77**
 78** First protocol.
 79** Server:
 80**
 81**   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
 82**   addr = PR_MemMap(fm); 
 83**   attr = PR_NewProcessAttr();
 84**   PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
 85**   PR_CreateProcess(Client); 
 86**   PR_DestroyProcessAttr(attr);
 87**   ... yadda ...
 88**   PR_MemUnmap( addr );
 89**   PR_CloseFileMap(fm);
 90**
 91**
 92** Client: 
 93**   ... started by server via PR_CreateProcess()
 94**   fm = PR_GetInheritedFileMap( shmname );
 95**   addr = PR_MemMap(fm);
 96**   ... yadda ...
 97**   PR_MemUnmap(addr);
 98**   PR_CloseFileMap(fm);
 99**
100**
101** Second Protocol:
102** Server:
103**
104**   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
105**   fmstring = PR_ExportFileMapAsString( fm );
106**   addr = PR_MemMap(fm); 
107**    ... application specific technique to pass fmstring to child
108**    ... yadda ... Server uses his own magic to create child
109**   PR_MemUnmap( addr );
110**   PR_CloseFileMap(fm);
111**
112**
113** Client: 
114**   ... started by server via his own magic
115**   ... application specific technique to find fmstring from parent
116**   fm = PR_ImportFileMapFromString( fmstring )
117**   addr = PR_MemMap(fm);
118**   ... yadda ...
119**   PR_MemUnmap(addr);
120**   PR_CloseFileMap(fm);
121**
122**
123** lth. 2-Jul-1999.
124**
125** Note: The second protocol was requested by NelsonB (7/1999); this is
126** to accomodate servers which already create their own child processes
127** using platform native methods.
128** 
129*/
130
131#ifndef prshma_h___
132#define prshma_h___
133
134#include "prtypes.h"
135#include "prio.h"
136#include "prproces.h"
137
138PR_BEGIN_EXTERN_C
139
140/*
141** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
142**
143** Description:
144** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
145** shared memory already exists, a handle is returned to that shared
146** memory object.
147**
148** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
149** directory name, without the trailing '/', to contain the anonymous
150** file. A filename is generated for the name.
151**
152** On Windows platforms, dirName is ignored.
153**
154** Inputs:
155**   dirName -- A directory name to contain the anonymous file.
156**   size -- The size of the shared memory
157**   prot -- How the shared memory is mapped. See prio.h
158**   
159** Outputs:
160**   PRFileMap *
161**
162** Returns:
163**   Pointer to PRFileMap or NULL on error.
164**
165*/
166NSPR_API( PRFileMap *)
167PR_OpenAnonFileMap(
168    const char *dirName,
169    PRSize      size, 
170    PRFileMapProtect prot
171);  
172
173/*
174** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export  
175**   to my children processes via PR_CreateProcess()
176**
177** Description:
178** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
179** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
180** makes the PRFileMap importable by the child process.
181**
182** Inputs:
183**   attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
184**   fm -- PRFileMap structure to be passed to the child process
185**   shmname -- The name for the PRFileMap; used by child.
186**
187** Outputs:
188**   PRFileMap *
189**
190** Returns:
191**   PRStatus
192**
193*/
194NSPR_API(PRStatus) 
195PR_ProcessAttrSetInheritableFileMap( 
196    PRProcessAttr   *attr,
197    PRFileMap       *fm, 
198    const char      *shmname
199);
200
201/*
202** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
203**   by my parent process via PR_CreateProcess()
204**
205** Description:
206** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
207** its parent process via PR_CreateProcess().
208**
209** Inputs:
210**    shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
211** 
212** Outputs:
213**   PRFileMap *
214**
215** Returns:
216**   PRFileMap pointer or NULL.
217**
218*/
219NSPR_API( PRFileMap *)
220PR_GetInheritedFileMap( 
221    const char *shmname 
222);
223
224/*
225** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
226**
227** Description:
228** Creates an identifier, as a string, from a PRFileMap object
229** previously created with PR_OpenAnonFileMap().
230**
231** Inputs:
232**   fm -- PRFileMap pointer to be represented as a string.
233**   bufsize -- sizeof(buf)
234**   buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
235**
236** Outputs:
237**   buf contains the stringized PRFileMap identifier
238**
239** Returns:
240**   PRStatus
241**
242*/
243NSPR_API( PRStatus )
244PR_ExportFileMapAsString( 
245    PRFileMap *fm,
246    PRSize    bufsize,
247    char      *buf
248);
249#define PR_FILEMAP_STRING_BUFSIZE 128
250
251/*
252** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
253**
254** Description:
255** PR_ImportFileMapFromString() creates a PRFileMap object from a
256** string previously created by PR_ExportFileMapAsString().
257**
258** Inputs:
259**   fmstring -- string created by PR_ExportFileMapAsString()
260**
261** Returns:
262**   PRFileMap pointer or NULL.
263**
264*/
265NSPR_API( PRFileMap * )
266PR_ImportFileMapFromString( 
267    const char *fmstring
268);
269
270PR_END_EXTERN_C
271#endif /* prshma_h___ */