named_shared_memory.rst (3796B)
1 The chapter describes the NSPR API for named shared memory. Shared 2 memory allows multiple processes to access one or more common shared 3 memory regions, using it as an interprocess communication channel. The 4 NSPR shared memory API provides a cross-platform named shared-memory 5 interface that is modeled on similar constructs in the Unix and Windows 6 operating systems. 7 8 - `Shared Memory Protocol <#Shared_Memory_Protocol>`__ 9 - `Named Shared Memory Functions <#Named_Shared_Memory_Functions>`__ 10 11 .. _Shared_Memory_Protocol: 12 13 Shared Memory Protocol 14 ---------------------- 15 16 .. _Using_Named_Shared_Memory_Functions: 17 18 Using Named Shared Memory Functions 19 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 20 21 :ref:`PR_OpenSharedMemory` creates the shared memory segment, if it does 22 not already exist, or opens a connection with the existing shared memory 23 segment if it already exists. 24 25 :ref:`PR_AttachSharedMemory` should be called following 26 :ref:`PR_OpenSharedMemory` to map the memory segment to an address in the 27 application's address space. :ref:`PR_AttachSharedMemory` may also be 28 called to remap a shared memory segment after detaching the same 29 ``PRSharedMemory`` object. Be sure to detach it when you're finished. 30 31 :ref:`PR_DetachSharedMemory` should be called to unmap the shared memory 32 segment from the application's address space. 33 34 :ref:`PR_CloseSharedMemory` should be called when no further use of the 35 ``PRSharedMemory`` object is required within a process. Following a call 36 to :ref:`PR_CloseSharedMemory`, the ``PRSharedMemory`` object is invalid 37 and cannot be reused. 38 39 :ref:`PR_DeleteSharedMemory` should be called before process termination. 40 After you call :ref:`PR_DeleteSharedMemory`, any further use of the shared 41 memory associated with the name may cause unpredictable results. 42 43 Filenames 44 ~~~~~~~~~ 45 46 The name passed to :ref:`PR_OpenSharedMemory` should be a valid filename 47 for a Unix platform. :ref:`PR_OpenSharedMemory` creates file using the name 48 passed in. Some platforms may mangle the name before creating the file 49 and the shared memory. The Unix implementation may use SysV IPC shared 50 memory, Posix shared memory, or memory mapped files; the filename may be 51 used to define the namespace. On Windows, the name is significant, but 52 there is no file associated with the name. 53 54 No assumptions about the persistence of data in the named file should be 55 made. Depending on platform, the shared memory may be mapped onto system 56 paging space and be discarded at process termination. 57 58 All names provided to :ref:`PR_OpenSharedMemory` should be valid filename 59 syntax or name syntax for shared memory for the target platform. 60 Referenced directories should have permissions appropriate for writing. 61 62 .. _Limits_on_Shared_Memory_Resources: 63 64 Limits on Shared Memory Resources 65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 66 67 Different platforms have limits on both the number and size of shared 68 memory resources. The default system limits on some platforms may be 69 smaller than your requirements. These limits may be adjusted on some 70 platforms either via boot-time options or by setting the size of the 71 system paging space to accommodate more and/or larger shared memory 72 segment(s). 73 74 .. _Security_Considerations: 75 76 Security Considerations 77 ~~~~~~~~~~~~~~~~~~~~~~~ 78 79 On Unix platforms, depending on implementation, contents of the backing 80 store for the shared memory can be exposed via the file system. Set 81 permissions and or access controls at create and attach time to ensure 82 you get the desired security. 83 84 On Windows platforms, no special security measures are provided. 85 86 .. _Named_Shared_Memory_Functions: 87 88 Named Shared Memory Functions 89 ----------------------------- 90 91 - :ref:`PR_OpenSharedMemory` 92 - :ref:`PR_AttachSharedMemory` 93 - :ref:`PR_DetachSharedMemory` 94 - :ref:`PR_CloseSharedMemory` 95 - :ref:`PR_DeleteSharedMemory`