PageRenderTime 39ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/gecko_api/include/prshma.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 271 lines | 35 code | 10 blank | 226 comment | 0 complexity | af20d9284b5131fc1fe1b64a6974a89b MD5 | raw file
  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___ */