michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /* michael@0: ** prshma.h -- NSPR Anonymous Shared Memory michael@0: ** michael@0: ** NSPR provides an anonymous shared memory based on NSPR's PRFileMap michael@0: ** type. The anonymous file-mapped shared memory provides an inheritable michael@0: ** shared memory, as in: the child process inherits the shared memory. michael@0: ** Compare the file-mapped anonymous shared memory to to a named shared michael@0: ** memory described in prshm.h. The intent is to provide a shared michael@0: ** memory that is accessable only by parent and child processes. ... michael@0: ** It's a security thing. michael@0: ** michael@0: ** Depending on the underlying platform, the file-mapped shared memory michael@0: ** may be backed by a file. ... surprise! ... On some platforms, no michael@0: ** real file backs the shared memory. On platforms where the shared michael@0: ** memory is backed by a file, the file's name in the filesystem is michael@0: ** visible to other processes for only the duration of the creation of michael@0: ** the file, hopefully a very short time. This restricts processess michael@0: ** that do not inherit the shared memory from opening the file and michael@0: ** reading or writing its contents. Further, when all processes michael@0: ** using an anonymous shared memory terminate, the backing file is michael@0: ** deleted. ... If you are not paranoid, you're not paying attention. michael@0: ** michael@0: ** The file-mapped shared memory requires a protocol for the parent michael@0: ** process and child process to share the memory. NSPR provides two michael@0: ** protocols. Use one or the other; don't mix and match. michael@0: ** michael@0: ** In the first protocol, the job of passing the inheritable shared michael@0: ** memory is done via helper-functions with PR_CreateProcess(). In the michael@0: ** second protocol, the parent process is responsible for creating the michael@0: ** child process; the parent and child are mutually responsible for michael@0: ** passing a FileMap string. NSPR provides helper functions for michael@0: ** extracting data from the PRFileMap object. ... See the examples michael@0: ** below. michael@0: ** michael@0: ** Both sides should adhere strictly to the protocol for proper michael@0: ** operation. The pseudo-code below shows the use of a file-mapped michael@0: ** shared memory by a parent and child processes. In the examples, the michael@0: ** server creates the file-mapped shared memory, the client attaches to michael@0: ** it. michael@0: ** michael@0: ** First protocol. michael@0: ** Server: michael@0: ** michael@0: ** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); michael@0: ** addr = PR_MemMap(fm); michael@0: ** attr = PR_NewProcessAttr(); michael@0: ** PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname ); michael@0: ** PR_CreateProcess(Client); michael@0: ** PR_DestroyProcessAttr(attr); michael@0: ** ... yadda ... michael@0: ** PR_MemUnmap( addr ); michael@0: ** PR_CloseFileMap(fm); michael@0: ** michael@0: ** michael@0: ** Client: michael@0: ** ... started by server via PR_CreateProcess() michael@0: ** fm = PR_GetInheritedFileMap( shmname ); michael@0: ** addr = PR_MemMap(fm); michael@0: ** ... yadda ... michael@0: ** PR_MemUnmap(addr); michael@0: ** PR_CloseFileMap(fm); michael@0: ** michael@0: ** michael@0: ** Second Protocol: michael@0: ** Server: michael@0: ** michael@0: ** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); michael@0: ** fmstring = PR_ExportFileMapAsString( fm ); michael@0: ** addr = PR_MemMap(fm); michael@0: ** ... application specific technique to pass fmstring to child michael@0: ** ... yadda ... Server uses his own magic to create child michael@0: ** PR_MemUnmap( addr ); michael@0: ** PR_CloseFileMap(fm); michael@0: ** michael@0: ** michael@0: ** Client: michael@0: ** ... started by server via his own magic michael@0: ** ... application specific technique to find fmstring from parent michael@0: ** fm = PR_ImportFileMapFromString( fmstring ) michael@0: ** addr = PR_MemMap(fm); michael@0: ** ... yadda ... michael@0: ** PR_MemUnmap(addr); michael@0: ** PR_CloseFileMap(fm); michael@0: ** michael@0: ** michael@0: ** lth. 2-Jul-1999. michael@0: ** michael@0: ** Note: The second protocol was requested by NelsonB (7/1999); this is michael@0: ** to accomodate servers which already create their own child processes michael@0: ** using platform native methods. michael@0: ** michael@0: */ michael@0: michael@0: #ifndef prshma_h___ michael@0: #define prshma_h___ michael@0: michael@0: #include "prtypes.h" michael@0: #include "prio.h" michael@0: #include "prproces.h" michael@0: michael@0: PR_BEGIN_EXTERN_C michael@0: michael@0: /* michael@0: ** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory michael@0: ** michael@0: ** Description: michael@0: ** PR_OpenAnonFileMap() creates an anonymous shared memory. If the michael@0: ** shared memory already exists, a handle is returned to that shared michael@0: ** memory object. michael@0: ** michael@0: ** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a michael@0: ** directory name, without the trailing '/', to contain the anonymous michael@0: ** file. A filename is generated for the name. michael@0: ** michael@0: ** On Windows platforms, dirName is ignored. michael@0: ** michael@0: ** Inputs: michael@0: ** dirName -- A directory name to contain the anonymous file. michael@0: ** size -- The size of the shared memory michael@0: ** prot -- How the shared memory is mapped. See prio.h michael@0: ** michael@0: ** Outputs: michael@0: ** PRFileMap * michael@0: ** michael@0: ** Returns: michael@0: ** Pointer to PRFileMap or NULL on error. michael@0: ** michael@0: */ michael@0: NSPR_API( PRFileMap *) michael@0: PR_OpenAnonFileMap( michael@0: const char *dirName, michael@0: PRSize size, michael@0: PRFileMapProtect prot michael@0: ); michael@0: michael@0: /* michael@0: ** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export michael@0: ** to my children processes via PR_CreateProcess() michael@0: ** michael@0: ** Description: michael@0: ** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to michael@0: ** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess() michael@0: ** makes the PRFileMap importable by the child process. michael@0: ** michael@0: ** Inputs: michael@0: ** attr -- PRProcessAttr, used to pass data to PR_CreateProcess() michael@0: ** fm -- PRFileMap structure to be passed to the child process michael@0: ** shmname -- The name for the PRFileMap; used by child. michael@0: ** michael@0: ** Outputs: michael@0: ** PRFileMap * michael@0: ** michael@0: ** Returns: michael@0: ** PRStatus michael@0: ** michael@0: */ michael@0: NSPR_API(PRStatus) michael@0: PR_ProcessAttrSetInheritableFileMap( michael@0: PRProcessAttr *attr, michael@0: PRFileMap *fm, michael@0: const char *shmname michael@0: ); michael@0: michael@0: /* michael@0: ** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported michael@0: ** by my parent process via PR_CreateProcess() michael@0: ** michael@0: ** Description: michael@0: ** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from michael@0: ** its parent process via PR_CreateProcess(). michael@0: ** michael@0: ** Inputs: michael@0: ** shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap() michael@0: ** michael@0: ** Outputs: michael@0: ** PRFileMap * michael@0: ** michael@0: ** Returns: michael@0: ** PRFileMap pointer or NULL. michael@0: ** michael@0: */ michael@0: NSPR_API( PRFileMap *) michael@0: PR_GetInheritedFileMap( michael@0: const char *shmname michael@0: ); michael@0: michael@0: /* michael@0: ** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap michael@0: ** michael@0: ** Description: michael@0: ** Creates an identifier, as a string, from a PRFileMap object michael@0: ** previously created with PR_OpenAnonFileMap(). michael@0: ** michael@0: ** Inputs: michael@0: ** fm -- PRFileMap pointer to be represented as a string. michael@0: ** bufsize -- sizeof(buf) michael@0: ** buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE michael@0: ** michael@0: ** Outputs: michael@0: ** buf contains the stringized PRFileMap identifier michael@0: ** michael@0: ** Returns: michael@0: ** PRStatus michael@0: ** michael@0: */ michael@0: NSPR_API( PRStatus ) michael@0: PR_ExportFileMapAsString( michael@0: PRFileMap *fm, michael@0: PRSize bufsize, michael@0: char *buf michael@0: ); michael@0: #define PR_FILEMAP_STRING_BUFSIZE 128 michael@0: michael@0: /* michael@0: ** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string michael@0: ** michael@0: ** Description: michael@0: ** PR_ImportFileMapFromString() creates a PRFileMap object from a michael@0: ** string previously created by PR_ExportFileMapAsString(). michael@0: ** michael@0: ** Inputs: michael@0: ** fmstring -- string created by PR_ExportFileMapAsString() michael@0: ** michael@0: ** Returns: michael@0: ** PRFileMap pointer or NULL. michael@0: ** michael@0: */ michael@0: NSPR_API( PRFileMap * ) michael@0: PR_ImportFileMapFromString( michael@0: const char *fmstring michael@0: ); michael@0: michael@0: PR_END_EXTERN_C michael@0: #endif /* prshma_h___ */