1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prshm.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,257 @@
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 +** prshm.h -- NSPR Shared Memory
1.11 +**
1.12 +** NSPR Named Shared Memory API provides a cross-platform named
1.13 +** shared-memory interface. NSPR Named Shared Memory is modeled on
1.14 +** similar constructs in Unix and Windows operating systems. Shared
1.15 +** memory allows multiple processes to access one or more common shared
1.16 +** memory regions, using it as an inter-process communication channel.
1.17 +**
1.18 +** Notes on Platform Independence:
1.19 +** NSPR Named Shared Memory is built on the native services offered
1.20 +** by most platforms. The NSPR Named Shared Memory API tries to
1.21 +** provide a least common denominator interface so that it works
1.22 +** across all supported platforms. To ensure that it works everywhere,
1.23 +** some platform considerations must be accomodated and the protocol
1.24 +** for using NSPR Shared Memory API must be observed.
1.25 +**
1.26 +** Protocol:
1.27 +** Multiple shared memories can be created using NSPR's Shared Memory
1.28 +** feature. For each named shared memory, as defined by the name
1.29 +** given in the PR_OpenSharedMemory() call, a protocol for using the
1.30 +** shared memory API is required to ensure desired behavior. Failing
1.31 +** to follow the protocol may yield unpredictable results.
1.32 +**
1.33 +** PR_OpenSharedMemory() will create the shared memory segment, if it
1.34 +** does not already exist, or open a connection that the existing
1.35 +** shared memory segment if it already exists.
1.36 +**
1.37 +** PR_AttachSharedMemory() should be called following
1.38 +** PR_OpenSharedMemory() to map the memory segment to an address in
1.39 +** the application's address space.
1.40 +**
1.41 +** PR_AttachSharedMemory() may be called to re-map a shared memory
1.42 +** segment after detaching the same PRSharedMemory object. Be
1.43 +** sure to detach it when done.
1.44 +**
1.45 +** PR_DetachSharedMemory() should be called to un-map the shared
1.46 +** memory segment from the application's address space.
1.47 +**
1.48 +** PR_CloseSharedMemory() should be called when no further use of the
1.49 +** PRSharedMemory object is required within a process. Following a
1.50 +** call to PR_CloseSharedMemory() the PRSharedMemory object is
1.51 +** invalid and cannot be reused.
1.52 +**
1.53 +** PR_DeleteSharedMemory() should be called before process
1.54 +** termination. After calling PR_DeleteSharedMemory() any further use
1.55 +** of the shared memory associated with the name may cause
1.56 +** unpredictable results.
1.57 +**
1.58 +** Files:
1.59 +** The name passed to PR_OpenSharedMemory() should be a valid filename
1.60 +** for a unix platform. PR_OpenSharedMemory() creates file using the
1.61 +** name passed in. Some platforms may mangle the name before creating
1.62 +** the file and the shared memory.
1.63 +**
1.64 +** The unix implementation may use SysV IPC shared memory, Posix
1.65 +** shared memory, or memory mapped files; the filename may used to
1.66 +** define the namespace. On Windows, the name is significant, but
1.67 +** there is no file associated with name.
1.68 +**
1.69 +** No assumptions about the persistence of data in the named file
1.70 +** should be made. Depending on platform, the shared memory may be
1.71 +** mapped onto system paging space and be discarded at process
1.72 +** termination.
1.73 +**
1.74 +** All names provided to PR_OpenSharedMemory() should be valid
1.75 +** filename syntax or name syntax for shared memory for the target
1.76 +** platform. Referenced directories should have permissions
1.77 +** appropriate for writing.
1.78 +**
1.79 +** Limits:
1.80 +** Different platforms have limits on both the number and size of
1.81 +** shared memory resources. The default system limits on some
1.82 +** platforms may be smaller than your requirements. These limits may
1.83 +** be adjusted on some platforms either via boot-time options or by
1.84 +** setting the size of the system paging space to accomodate more
1.85 +** and/or larger shared memory segment(s).
1.86 +**
1.87 +** Security:
1.88 +** On unix platforms, depending on implementation, contents of the
1.89 +** backing store for the shared memory can be exposed via the file
1.90 +** system. Set permissions and or access controls at create and attach
1.91 +** time to ensure you get the desired security.
1.92 +**
1.93 +** On windows platforms, no special security measures are provided.
1.94 +**
1.95 +** Example:
1.96 +** The test case pr/tests/nameshm1.c provides an example of use as
1.97 +** well as testing the operation of NSPR's Named Shared Memory.
1.98 +**
1.99 +** lth. 18-Aug-1999.
1.100 +*/
1.101 +
1.102 +#ifndef prshm_h___
1.103 +#define prshm_h___
1.104 +
1.105 +#include "prtypes.h"
1.106 +#include "prio.h"
1.107 +
1.108 +PR_BEGIN_EXTERN_C
1.109 +
1.110 +/*
1.111 +** Declare opaque type PRSharedMemory.
1.112 +*/
1.113 +typedef struct PRSharedMemory PRSharedMemory;
1.114 +
1.115 +/*
1.116 +** FUNCTION: PR_OpenSharedMemory()
1.117 +**
1.118 +** DESCRIPTION:
1.119 +** PR_OpenSharedMemory() creates a new shared-memory segment or
1.120 +** associates a previously created memory segment with name.
1.121 +**
1.122 +** When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
1.123 +** shared memory already exists, the function returns NULL with the
1.124 +** error set to PR_FILE_EXISTS_ERROR.
1.125 +**
1.126 +** When parameter create is PR_SHM_CREATE and the shared memory
1.127 +** already exists, a handle to that memory segment is returned. If
1.128 +** the segment does not exist, it is created and a pointer to the
1.129 +** related PRSharedMemory structure is returned.
1.130 +**
1.131 +** When parameter create is 0, and the shared memory exists, a
1.132 +** pointer to a PRSharedMemory is returned. If the shared memory does
1.133 +** not exist, NULL is returned with the error set to
1.134 +** PR_FILE_NOT_FOUND_ERROR.
1.135 +**
1.136 +** INPUTS:
1.137 +** name -- the name the shared-memory segment is known as.
1.138 +** size -- the size of the shared memory segment.
1.139 +** flags -- Options for creating the shared memory
1.140 +** mode -- Same as is passed to PR_Open()
1.141 +**
1.142 +** OUTPUTS:
1.143 +** The shared memory is allocated.
1.144 +**
1.145 +** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
1.146 +** NULL is returned on error. The reason for the error can be
1.147 +** retrieved via PR_GetError() and PR_GetOSError();
1.148 +**
1.149 +*/
1.150 +NSPR_API( PRSharedMemory * )
1.151 + PR_OpenSharedMemory(
1.152 + const char *name,
1.153 + PRSize size,
1.154 + PRIntn flags,
1.155 + PRIntn mode
1.156 +);
1.157 +/* Define values for PR_OpenShareMemory(...,create) */
1.158 +#define PR_SHM_CREATE 0x1 /* create if not exist */
1.159 +#define PR_SHM_EXCL 0x2 /* fail if already exists */
1.160 +
1.161 +/*
1.162 +** FUNCTION: PR_AttachSharedMemory()
1.163 +**
1.164 +** DESCRIPTION:
1.165 +** PR_AttachSharedMemory() maps the shared-memory described by
1.166 +** shm to the current process.
1.167 +**
1.168 +** INPUTS:
1.169 +** shm -- The handle returned from PR_OpenSharedMemory().
1.170 +** flags -- options for mapping the shared memory.
1.171 +** PR_SHM_READONLY causes the memory to be attached
1.172 +** read-only.
1.173 +**
1.174 +** OUTPUTS:
1.175 +** On success, the shared memory segment represented by shm is mapped
1.176 +** into the process' address space.
1.177 +**
1.178 +** RETURNS: Address where shared memory is mapped, or NULL.
1.179 +** NULL is returned on error. The reason for the error can be
1.180 +** retrieved via PR_GetError() and PR_GetOSError();
1.181 +**
1.182 +**
1.183 +*/
1.184 +NSPR_API( void * )
1.185 + PR_AttachSharedMemory(
1.186 + PRSharedMemory *shm,
1.187 + PRIntn flags
1.188 +);
1.189 +/* Define values for PR_AttachSharedMemory(...,flags) */
1.190 +#define PR_SHM_READONLY 0x01
1.191 +
1.192 +/*
1.193 +** FUNCTION: PR_DetachSharedMemory()
1.194 +**
1.195 +** DESCRIPTION:
1.196 +** PR_DetachSharedMemory() detaches the shared-memory described
1.197 +** by shm.
1.198 +**
1.199 +** INPUTS:
1.200 +** shm -- The handle returned from PR_OpenSharedMemory().
1.201 +** addr -- The address at which the memory was attached.
1.202 +**
1.203 +** OUTPUTS:
1.204 +** The shared memory mapped to an address via a previous call to
1.205 +** PR_AttachSharedMemory() is unmapped.
1.206 +**
1.207 +** RETURNS: PRStatus
1.208 +**
1.209 +*/
1.210 +NSPR_API( PRStatus )
1.211 + PR_DetachSharedMemory(
1.212 + PRSharedMemory *shm,
1.213 + void *addr
1.214 +);
1.215 +
1.216 +/*
1.217 +** FUNCTION: PR_CloseSharedMemory()
1.218 +**
1.219 +** DESCRIPTION:
1.220 +** PR_CloseSharedMemory() closes the shared-memory described by
1.221 +** shm.
1.222 +**
1.223 +** INPUTS:
1.224 +** shm -- The handle returned from PR_OpenSharedMemory().
1.225 +**
1.226 +** OUTPUTS:
1.227 +** the shared memory represented by shm is closed
1.228 +**
1.229 +** RETURNS: PRStatus
1.230 +**
1.231 +*/
1.232 +NSPR_API( PRStatus )
1.233 + PR_CloseSharedMemory(
1.234 + PRSharedMemory *shm
1.235 +);
1.236 +
1.237 +/*
1.238 +** FUNCTION: PR_DeleteSharedMemory()
1.239 +**
1.240 +** DESCRIPTION:
1.241 +** The shared memory resource represented by name is released.
1.242 +**
1.243 +** INPUTS:
1.244 +** name -- the name the shared-memory segment
1.245 +**
1.246 +** OUTPUTS:
1.247 +** depending on platform, resources may be returned to the underlying
1.248 +** operating system.
1.249 +**
1.250 +** RETURNS: PRStatus
1.251 +**
1.252 +*/
1.253 +NSPR_API( PRStatus )
1.254 + PR_DeleteSharedMemory(
1.255 + const char *name
1.256 +);
1.257 +
1.258 +PR_END_EXTERN_C
1.259 +
1.260 +#endif /* prshm_h___ */
