prshma.h (7138B)
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___ */