third_party/npapi/npspy/extern/nspr/prshma.h

   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___ */