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