1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prshma.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,239 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 +** prshma.h -- NSPR Anonymous Shared Memory
1.11 +**
1.12 +** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
1.13 +** type. The anonymous file-mapped shared memory provides an inheritable
1.14 +** shared memory, as in: the child process inherits the shared memory.
1.15 +** Compare the file-mapped anonymous shared memory to to a named shared
1.16 +** memory described in prshm.h. The intent is to provide a shared
1.17 +** memory that is accessable only by parent and child processes. ...
1.18 +** It's a security thing.
1.19 +**
1.20 +** Depending on the underlying platform, the file-mapped shared memory
1.21 +** may be backed by a file. ... surprise! ... On some platforms, no
1.22 +** real file backs the shared memory. On platforms where the shared
1.23 +** memory is backed by a file, the file's name in the filesystem is
1.24 +** visible to other processes for only the duration of the creation of
1.25 +** the file, hopefully a very short time. This restricts processess
1.26 +** that do not inherit the shared memory from opening the file and
1.27 +** reading or writing its contents. Further, when all processes
1.28 +** using an anonymous shared memory terminate, the backing file is
1.29 +** deleted. ... If you are not paranoid, you're not paying attention.
1.30 +**
1.31 +** The file-mapped shared memory requires a protocol for the parent
1.32 +** process and child process to share the memory. NSPR provides two
1.33 +** protocols. Use one or the other; don't mix and match.
1.34 +**
1.35 +** In the first protocol, the job of passing the inheritable shared
1.36 +** memory is done via helper-functions with PR_CreateProcess(). In the
1.37 +** second protocol, the parent process is responsible for creating the
1.38 +** child process; the parent and child are mutually responsible for
1.39 +** passing a FileMap string. NSPR provides helper functions for
1.40 +** extracting data from the PRFileMap object. ... See the examples
1.41 +** below.
1.42 +**
1.43 +** Both sides should adhere strictly to the protocol for proper
1.44 +** operation. The pseudo-code below shows the use of a file-mapped
1.45 +** shared memory by a parent and child processes. In the examples, the
1.46 +** server creates the file-mapped shared memory, the client attaches to
1.47 +** it.
1.48 +**
1.49 +** First protocol.
1.50 +** Server:
1.51 +**
1.52 +** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt);
1.53 +** addr = PR_MemMap(fm);
1.54 +** attr = PR_NewProcessAttr();
1.55 +** PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
1.56 +** PR_CreateProcess(Client);
1.57 +** PR_DestroyProcessAttr(attr);
1.58 +** ... yadda ...
1.59 +** PR_MemUnmap( addr );
1.60 +** PR_CloseFileMap(fm);
1.61 +**
1.62 +**
1.63 +** Client:
1.64 +** ... started by server via PR_CreateProcess()
1.65 +** fm = PR_GetInheritedFileMap( shmname );
1.66 +** addr = PR_MemMap(fm);
1.67 +** ... yadda ...
1.68 +** PR_MemUnmap(addr);
1.69 +** PR_CloseFileMap(fm);
1.70 +**
1.71 +**
1.72 +** Second Protocol:
1.73 +** Server:
1.74 +**
1.75 +** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt);
1.76 +** fmstring = PR_ExportFileMapAsString( fm );
1.77 +** addr = PR_MemMap(fm);
1.78 +** ... application specific technique to pass fmstring to child
1.79 +** ... yadda ... Server uses his own magic to create child
1.80 +** PR_MemUnmap( addr );
1.81 +** PR_CloseFileMap(fm);
1.82 +**
1.83 +**
1.84 +** Client:
1.85 +** ... started by server via his own magic
1.86 +** ... application specific technique to find fmstring from parent
1.87 +** fm = PR_ImportFileMapFromString( fmstring )
1.88 +** addr = PR_MemMap(fm);
1.89 +** ... yadda ...
1.90 +** PR_MemUnmap(addr);
1.91 +** PR_CloseFileMap(fm);
1.92 +**
1.93 +**
1.94 +** lth. 2-Jul-1999.
1.95 +**
1.96 +** Note: The second protocol was requested by NelsonB (7/1999); this is
1.97 +** to accomodate servers which already create their own child processes
1.98 +** using platform native methods.
1.99 +**
1.100 +*/
1.101 +
1.102 +#ifndef prshma_h___
1.103 +#define prshma_h___
1.104 +
1.105 +#include "prtypes.h"
1.106 +#include "prio.h"
1.107 +#include "prproces.h"
1.108 +
1.109 +PR_BEGIN_EXTERN_C
1.110 +
1.111 +/*
1.112 +** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
1.113 +**
1.114 +** Description:
1.115 +** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
1.116 +** shared memory already exists, a handle is returned to that shared
1.117 +** memory object.
1.118 +**
1.119 +** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
1.120 +** directory name, without the trailing '/', to contain the anonymous
1.121 +** file. A filename is generated for the name.
1.122 +**
1.123 +** On Windows platforms, dirName is ignored.
1.124 +**
1.125 +** Inputs:
1.126 +** dirName -- A directory name to contain the anonymous file.
1.127 +** size -- The size of the shared memory
1.128 +** prot -- How the shared memory is mapped. See prio.h
1.129 +**
1.130 +** Outputs:
1.131 +** PRFileMap *
1.132 +**
1.133 +** Returns:
1.134 +** Pointer to PRFileMap or NULL on error.
1.135 +**
1.136 +*/
1.137 +NSPR_API( PRFileMap *)
1.138 +PR_OpenAnonFileMap(
1.139 + const char *dirName,
1.140 + PRSize size,
1.141 + PRFileMapProtect prot
1.142 +);
1.143 +
1.144 +/*
1.145 +** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export
1.146 +** to my children processes via PR_CreateProcess()
1.147 +**
1.148 +** Description:
1.149 +** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
1.150 +** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
1.151 +** makes the PRFileMap importable by the child process.
1.152 +**
1.153 +** Inputs:
1.154 +** attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
1.155 +** fm -- PRFileMap structure to be passed to the child process
1.156 +** shmname -- The name for the PRFileMap; used by child.
1.157 +**
1.158 +** Outputs:
1.159 +** PRFileMap *
1.160 +**
1.161 +** Returns:
1.162 +** PRStatus
1.163 +**
1.164 +*/
1.165 +NSPR_API(PRStatus)
1.166 +PR_ProcessAttrSetInheritableFileMap(
1.167 + PRProcessAttr *attr,
1.168 + PRFileMap *fm,
1.169 + const char *shmname
1.170 +);
1.171 +
1.172 +/*
1.173 +** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
1.174 +** by my parent process via PR_CreateProcess()
1.175 +**
1.176 +** Description:
1.177 +** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
1.178 +** its parent process via PR_CreateProcess().
1.179 +**
1.180 +** Inputs:
1.181 +** shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
1.182 +**
1.183 +** Outputs:
1.184 +** PRFileMap *
1.185 +**
1.186 +** Returns:
1.187 +** PRFileMap pointer or NULL.
1.188 +**
1.189 +*/
1.190 +NSPR_API( PRFileMap *)
1.191 +PR_GetInheritedFileMap(
1.192 + const char *shmname
1.193 +);
1.194 +
1.195 +/*
1.196 +** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
1.197 +**
1.198 +** Description:
1.199 +** Creates an identifier, as a string, from a PRFileMap object
1.200 +** previously created with PR_OpenAnonFileMap().
1.201 +**
1.202 +** Inputs:
1.203 +** fm -- PRFileMap pointer to be represented as a string.
1.204 +** bufsize -- sizeof(buf)
1.205 +** buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
1.206 +**
1.207 +** Outputs:
1.208 +** buf contains the stringized PRFileMap identifier
1.209 +**
1.210 +** Returns:
1.211 +** PRStatus
1.212 +**
1.213 +*/
1.214 +NSPR_API( PRStatus )
1.215 +PR_ExportFileMapAsString(
1.216 + PRFileMap *fm,
1.217 + PRSize bufsize,
1.218 + char *buf
1.219 +);
1.220 +#define PR_FILEMAP_STRING_BUFSIZE 128
1.221 +
1.222 +/*
1.223 +** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
1.224 +**
1.225 +** Description:
1.226 +** PR_ImportFileMapFromString() creates a PRFileMap object from a
1.227 +** string previously created by PR_ExportFileMapAsString().
1.228 +**
1.229 +** Inputs:
1.230 +** fmstring -- string created by PR_ExportFileMapAsString()
1.231 +**
1.232 +** Returns:
1.233 +** PRFileMap pointer or NULL.
1.234 +**
1.235 +*/
1.236 +NSPR_API( PRFileMap * )
1.237 +PR_ImportFileMapFromString(
1.238 + const char *fmstring
1.239 +);
1.240 +
1.241 +PR_END_EXTERN_C
1.242 +#endif /* prshma_h___ */
