libraries/source/spidermonkey/include-win32-release/nspr/prshma.h

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