prshma.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:8k
源码类别:

PlugIns编程

开发平台:

Visual C++

  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1999-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37. /*
  38. ** prshma.h -- NSPR Anonymous Shared Memory
  39. **
  40. ** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
  41. ** type. The anonymous file-mapped shared memory provides an inheritable
  42. ** shared memory, as in: the child process inherits the shared memory.
  43. ** Compare the file-mapped anonymous shared memory to to a named shared
  44. ** memory described in prshm.h. The intent is to provide a shared
  45. ** memory that is accessable only by parent and child processes. ...
  46. ** It's a security thing.
  47. ** 
  48. ** Depending on the underlying platform, the file-mapped shared memory
  49. ** may be backed by a file. ... surprise! ... On some platforms, no
  50. ** real file backs the shared memory. On platforms where the shared
  51. ** memory is backed by a file, the file's name in the filesystem is
  52. ** visible to other processes for only the duration of the creation of
  53. ** the file, hopefully a very short time. This restricts processess
  54. ** that do not inherit the shared memory from opening the file and
  55. ** reading or writing its contents. Further, when all processes
  56. ** using an anonymous shared memory terminate, the backing file is
  57. ** deleted. ... If you are not paranoid, you're not paying attention.
  58. ** 
  59. ** The file-mapped shared memory requires a protocol for the parent
  60. ** process and child process to share the memory. NSPR provides two
  61. ** protocols. Use one or the other; don't mix and match.
  62. ** 
  63. ** In the first protocol, the job of passing the inheritable shared
  64. ** memory is done via helper-functions with PR_CreateProcess(). In the
  65. ** second protocol, the parent process is responsible for creating the
  66. ** child process; the parent and child are mutually responsible for
  67. ** passing a FileMap string. NSPR provides helper functions for
  68. ** extracting data from the PRFileMap object. ... See the examples
  69. ** below.
  70. ** 
  71. ** Both sides should adhere strictly to the protocol for proper
  72. ** operation. The pseudo-code below shows the use of a file-mapped
  73. ** shared memory by a parent and child processes. In the examples, the
  74. ** server creates the file-mapped shared memory, the client attaches to
  75. ** it.
  76. **
  77. ** First protocol.
  78. ** Server:
  79. **
  80. **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
  81. **   addr = PR_MemMap(fm); 
  82. **   attr = PR_NewProcessAttr();
  83. **   PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
  84. **   PR_CreateProcess(Client); 
  85. **   PR_DestroyProcessAttr(attr);
  86. **   ... yadda ...
  87. **   PR_MemUnmap( addr );
  88. **   PR_CloseFileMap(fm);
  89. **
  90. **
  91. ** Client: 
  92. **   ... started by server via PR_CreateProcess()
  93. **   fm = PR_GetInheritedFileMap( shmname );
  94. **   addr = PR_MemMap(fm);
  95. **   ... yadda ...
  96. **   PR_MemUnmap(addr);
  97. **   PR_CloseFileMap(fm);
  98. **
  99. **
  100. ** Second Protocol:
  101. ** Server:
  102. **
  103. **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
  104. **   fmstring = PR_ExportFileMapAsString( fm );
  105. **   addr = PR_MemMap(fm); 
  106. **    ... application specific technique to pass fmstring to child
  107. **    ... yadda ... Server uses his own magic to create child
  108. **   PR_MemUnmap( addr );
  109. **   PR_CloseFileMap(fm);
  110. **
  111. **
  112. ** Client: 
  113. **   ... started by server via his own magic
  114. **   ... application specific technique to find fmstring from parent
  115. **   fm = PR_ImportFileMapFromString( fmstring )
  116. **   addr = PR_MemMap(fm);
  117. **   ... yadda ...
  118. **   PR_MemUnmap(addr);
  119. **   PR_CloseFileMap(fm);
  120. **
  121. **
  122. ** lth. 2-Jul-1999.
  123. **
  124. ** Note: The second protocol was requested by NelsonB (7/1999); this is
  125. ** to accomodate servers which already create their own child processes
  126. ** using platform native methods.
  127. ** 
  128. */
  129. #ifndef prshma_h___
  130. #define prshma_h___
  131. #include "prtypes.h"
  132. #include "prio.h"
  133. #include "prproces.h"
  134. PR_BEGIN_EXTERN_C
  135. /*
  136. ** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
  137. **
  138. ** Description:
  139. ** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
  140. ** shared memory already exists, a handle is returned to that shared
  141. ** memory object.
  142. **
  143. ** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
  144. ** directory name, without the trailing '/', to contain the anonymous
  145. ** file. A filename is generated for the name.
  146. **
  147. ** On Windows platforms, dirName is ignored.
  148. **
  149. ** Inputs:
  150. **   dirName -- A directory name to contain the anonymous file.
  151. **   size -- The size of the shared memory
  152. **   prot -- How the shared memory is mapped. See prio.h
  153. **   
  154. ** Outputs:
  155. **   PRFileMap *
  156. **
  157. ** Returns:
  158. **   Pointer to PRFileMap or NULL on error.
  159. **
  160. */
  161. NSPR_API( PRFileMap *)
  162. PR_OpenAnonFileMap(
  163.     const char *dirName,
  164.     PRSize      size, 
  165.     PRFileMapProtect prot
  166. );  
  167. /*
  168. ** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export  
  169. **   to my children processes via PR_CreateProcess()
  170. **
  171. ** Description:
  172. ** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
  173. ** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
  174. ** makes the PRFileMap importable by the child process.
  175. **
  176. ** Inputs:
  177. **   attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
  178. **   fm -- PRFileMap structure to be passed to the child process
  179. **   shmname -- The name for the PRFileMap; used by child.
  180. **
  181. ** Outputs:
  182. **   PRFileMap *
  183. **
  184. ** Returns:
  185. **   PRStatus
  186. **
  187. */
  188. NSPR_API(PRStatus) 
  189. PR_ProcessAttrSetInheritableFileMap( 
  190.     PRProcessAttr   *attr,
  191.     PRFileMap       *fm, 
  192.     const char      *shmname
  193. );
  194. /*
  195. ** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
  196. **   by my parent process via PR_CreateProcess()
  197. **
  198. ** Description:
  199. ** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
  200. ** its parent process via PR_CreateProcess().
  201. **
  202. ** Inputs:
  203. **    shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
  204. ** 
  205. ** Outputs:
  206. **   PRFileMap *
  207. **
  208. ** Returns:
  209. **   PRFileMap pointer or NULL.
  210. **
  211. */
  212. NSPR_API( PRFileMap *)
  213. PR_GetInheritedFileMap( 
  214.     const char *shmname 
  215. );
  216. /*
  217. ** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
  218. **
  219. ** Description:
  220. ** Creates an identifier, as a string, from a PRFileMap object
  221. ** previously created with PR_OpenAnonFileMap().
  222. **
  223. ** Inputs:
  224. **   fm -- PRFileMap pointer to be represented as a string.
  225. **   bufsize -- sizeof(buf)
  226. **   buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
  227. **
  228. ** Outputs:
  229. **   buf contains the stringized PRFileMap identifier
  230. **
  231. ** Returns:
  232. **   PRStatus
  233. **
  234. */
  235. NSPR_API( PRStatus )
  236. PR_ExportFileMapAsString( 
  237.     PRFileMap *fm,
  238.     PRSize    bufsize,
  239.     char      *buf
  240. );
  241. #define PR_FILEMAP_STRING_BUFSIZE 128
  242. /*
  243. ** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
  244. **
  245. ** Description:
  246. ** PR_ImportFileMapFromString() creates a PRFileMap object from a
  247. ** string previously created by PR_ExportFileMapAsString().
  248. **
  249. ** Inputs:
  250. **   fmstring -- string created by PR_ExportFileMapAsString()
  251. **
  252. ** Returns:
  253. **   PRFileMap pointer or NULL.
  254. **
  255. */
  256. NSPR_API( PRFileMap * )
  257. PR_ImportFileMapFromString( 
  258.     const char *fmstring
  259. );
  260. PR_END_EXTERN_C
  261. #endif /* prshma_h___ */