diff options
Diffstat (limited to 'docs/nspr/reference/anonymous_shared_memory.rst')
| -rw-r--r-- | docs/nspr/reference/anonymous_shared_memory.rst | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/docs/nspr/reference/anonymous_shared_memory.rst b/docs/nspr/reference/anonymous_shared_memory.rst new file mode 100644 index 0000000000..3daea2cbb0 --- /dev/null +++ b/docs/nspr/reference/anonymous_shared_memory.rst @@ -0,0 +1,118 @@ +Anonymous Shared Memory +======================= + +This chapter describes the NSPR API for anonymous shared memory. + +- `Anonymous Memory Protocol <#Anonymous_Memory_Protocol>`__ +- `Anonymous Shared Memory + Functions <#Anonymous_Shared_Memory_Functions>`__ + +.. _Anonymous_Memory_Protocol: + +Anonymous Memory Protocol +------------------------- + +NSPR provides an anonymous shared memory based on NSPR's :ref:`PRFileMap` +type. The anonymous file-mapped shared memory provides an inheritable +shared memory, as in: the child process inherits the shared memory. +Compare the file-mapped anonymous shared memory to to a named shared +memory described in prshm.h. The intent is to provide a shared memory +that is accessible only by parent and child processes. ... It's a +security thing. + +Depending on the underlying platform, the file-mapped shared memory may +be backed by a file. ... surprise! ... On some platforms, no real file +backs the shared memory. On platforms where the shared memory is backed +by a file, the file's name in the filesystem is visible to other +processes for only the duration of the creation of the file, hopefully a +very short time. This restricts processes that do not inherit the shared +memory from opening the file and reading or writing its contents. +Further, when all processes using an anonymous shared memory terminate, +the backing file is deleted. ... If you are not paranoid, you're not +paying attention. + +The file-mapped shared memory requires a protocol for the parent process +and child process to share the memory. NSPR provides two protocols. Use +one or the other; don't mix and match. + +In the first protocol, the job of passing the inheritable shared memory +is done via helper-functions with PR_CreateProcess. In the second +protocol, the parent process is responsible for creating the child +process; the parent and child are mutually responsible for passing a +``FileMap`` string. NSPR provides helper functions for extracting data +from the :ref:`PRFileMap` object. ... See the examples below. + +Both sides should adhere strictly to the protocol for proper operation. +The pseudo-code below shows the use of a file-mapped shared memory by a +parent and child processes. In the examples, the server creates the +file-mapped shared memory, the client attaches to it. + +.. _First_protocol: + +First protocol +~~~~~~~~~~~~~~ + +**Server:** + +.. code:: + + fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); + addr = PR_MemMap(fm); + attr = PR_NewProcessAttr(); + PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname ); + PR_CreateProcess(Client); + PR_DestroyProcessAttr(attr); + ... yadda ... + PR_MemUnmap( addr ); + PR_CloseFileMap(fm); + +**Client:** + +.. code:: + + ... started by server via PR_CreateProcess() + fm = PR_GetInheritedFileMap( shmname ); + addr = PR_MemMap(fm); + ... yadda ... + PR_MemUnmap(addr); + PR_CloseFileMap(fm); + +.. _Second_protocol: + +Second protocol +~~~~~~~~~~~~~~~ + +**Server:** + +.. code:: + + fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); + fmstring = PR_ExportFileMapAsString( fm ); + addr = PR_MemMap(fm); + ... application specific technique to pass fmstring to child + ... yadda ... Server uses his own magic to create child + PR_MemUnmap( addr ); + PR_CloseFileMap(fm); + +**Client:** + +.. code:: + + ... started by server via his own magic + ... application specific technique to find fmstring from parent + fm = PR_ImportFileMapFromString( fmstring ) + addr = PR_MemMap(fm); + ... yadda ... + PR_MemUnmap(addr); + PR_CloseFileMap(fm); + +.. _Anonymous_Shared_Memory_Functions: + +Anonymous Shared Memory Functions +--------------------------------- + +- :ref:`PR_OpenAnonFileMap` +- :ref:`PR_ProcessAttrSetInheritableFileMap` +- :ref:`PR_GetInheritedFileMap` +- :ref:`PR_ExportFileMapAsString` +- :ref:`PR_ImportFileMapFromString` |