tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

prshm.h (8468B)

      1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
      2 /* This Source Code Form is subject to the terms of the Mozilla Public
      3 * License, v. 2.0. If a copy of the MPL was not distributed with this
      4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
      5 
      6 /*
      7 ** prshm.h -- NSPR Shared Memory
      8 **
      9 ** NSPR Named Shared Memory API provides a cross-platform named
     10 ** shared-memory interface. NSPR Named Shared Memory is modeled on
     11 ** similar constructs in Unix and Windows operating systems. Shared
     12 ** memory allows multiple processes to access one or more common shared
     13 ** memory regions, using it as an inter-process communication channel.
     14 **
     15 ** Notes on Platform Independence:
     16 **   NSPR Named Shared Memory is built on the native services offered
     17 **   by most platforms. The NSPR Named Shared Memory API tries to
     18 **   provide a least common denominator interface so that it works
     19 **   across all supported platforms. To ensure that it works everywhere,
     20 **   some platform considerations must be accomodated and the protocol
     21 **   for using NSPR Shared Memory API must be observed.
     22 **
     23 ** Protocol:
     24 **   Multiple shared memories can be created using NSPR's Shared Memory
     25 **   feature. For each named shared memory, as defined by the name
     26 **   given in the PR_OpenSharedMemory() call, a protocol for using the
     27 **   shared memory API is required to ensure desired behavior. Failing
     28 **   to follow the protocol may yield unpredictable results.
     29 **
     30 **   PR_OpenSharedMemory() will create the shared memory segment, if it
     31 **   does not already exist, or open a connection that the existing
     32 **   shared memory segment if it already exists.
     33 **
     34 **   PR_AttachSharedMemory() should be called following
     35 **   PR_OpenSharedMemory() to map the memory segment to an address in
     36 **   the application's address space.
     37 **
     38 **   PR_AttachSharedMemory() may be called to re-map a shared memory
     39 **   segment after detaching the same PRSharedMemory object. Be
     40 **   sure to detach it when done.
     41 **
     42 **   PR_DetachSharedMemory() should be called to un-map the shared
     43 **   memory segment from the application's address space.
     44 **
     45 **   PR_CloseSharedMemory() should be called when no further use of the
     46 **   PRSharedMemory object is required within a process. Following a
     47 **   call to  PR_CloseSharedMemory() the PRSharedMemory object is
     48 **   invalid and cannot be reused.
     49 **
     50 **   PR_DeleteSharedMemory() should be called before process
     51 **   termination. After calling PR_DeleteSharedMemory() any further use
     52 **   of the shared memory associated with the name may cause
     53 **   unpredictable results.
     54 **
     55 ** Files:
     56 **   The name passed to PR_OpenSharedMemory() should be a valid filename
     57 **   for a unix platform. PR_OpenSharedMemory() creates file using the
     58 **   name passed in. Some platforms may mangle the name before creating
     59 **   the file and the shared memory.
     60 **
     61 **   The unix implementation may use SysV IPC shared memory, Posix
     62 **   shared memory, or memory mapped files; the filename may used to
     63 **   define the namespace. On Windows, the name is significant, but
     64 **   there is no file associated with name.
     65 **
     66 **   No assumptions about the persistence of data in the named file
     67 **   should be made. Depending on platform, the shared memory may be
     68 **   mapped onto system paging space and be discarded at process
     69 **   termination.
     70 **
     71 **   All names provided to PR_OpenSharedMemory() should be valid
     72 **   filename syntax or name syntax for shared memory for the target
     73 **   platform. Referenced directories should have permissions
     74 **   appropriate for writing.
     75 **
     76 ** Limits:
     77 **   Different platforms have limits on both the number and size of
     78 **   shared memory resources. The default system limits on some
     79 **   platforms may be smaller than your requirements. These limits may
     80 **   be adjusted on some platforms either via boot-time options or by
     81 **   setting the size of the system paging space to accomodate more
     82 **   and/or larger shared memory segment(s).
     83 **
     84 ** Security:
     85 **   On unix platforms, depending on implementation, contents of the
     86 **   backing store for the shared memory can be exposed via the file
     87 **   system. Set permissions and or access controls at create and attach
     88 **   time to ensure you get the desired security.
     89 **
     90 **   On windows platforms, no special security measures are provided.
     91 **
     92 ** Example:
     93 **   The test case pr/tests/nameshm1.c provides an example of use as
     94 **   well as testing the operation of NSPR's Named Shared Memory.
     95 **
     96 ** lth. 18-Aug-1999.
     97 */
     98 
     99 #ifndef prshm_h___
    100 #define prshm_h___
    101 
    102 #include "prtypes.h"
    103 #include "prio.h"
    104 
    105 PR_BEGIN_EXTERN_C
    106 
    107 /*
    108 ** Declare opaque type PRSharedMemory.
    109 */
    110 typedef struct PRSharedMemory PRSharedMemory;
    111 
    112 /*
    113 ** FUNCTION: PR_OpenSharedMemory()
    114 **
    115 ** DESCRIPTION:
    116 **   PR_OpenSharedMemory() creates a new shared-memory segment or
    117 **   associates a previously created memory segment with name.
    118 **
    119 **   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
    120 **   shared memory already exists, the function returns NULL with the
    121 **   error set to PR_FILE_EXISTS_ERROR.
    122 **
    123 **   When parameter create is PR_SHM_CREATE and the shared memory
    124 **   already exists, a handle to that memory segment is returned. If
    125 **   the segment does not exist, it is created and a pointer to the
    126 **   related PRSharedMemory structure is returned.
    127 **
    128 **   When parameter create is 0, and the shared memory exists, a
    129 **   pointer to a PRSharedMemory is returned. If the shared memory does
    130 **   not exist, NULL is returned with the error set to
    131 **   PR_FILE_NOT_FOUND_ERROR.
    132 **
    133 ** INPUTS:
    134 **   name -- the name the shared-memory segment is known as.
    135 **   size -- the size of the shared memory segment.
    136 **   flags -- Options for creating the shared memory
    137 **   mode -- Same as is passed to PR_Open()
    138 **
    139 ** OUTPUTS:
    140 **   The shared memory is allocated.
    141 **
    142 ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
    143 **   NULL is returned on error. The reason for the error can be
    144 **   retrieved via PR_GetError() and PR_GetOSError();
    145 **
    146 */
    147 NSPR_API( PRSharedMemory * )
    148 PR_OpenSharedMemory(
    149    const char *name,
    150    PRSize      size,
    151    PRIntn      flags,
    152    PRIntn      mode
    153 );
    154 /* Define values for PR_OpenShareMemory(...,create) */
    155 #define PR_SHM_CREATE 0x1  /* create if not exist */
    156 #define PR_SHM_EXCL   0x2  /* fail if already exists */
    157 
    158 /*
    159 ** FUNCTION: PR_AttachSharedMemory()
    160 **
    161 ** DESCRIPTION:
    162 ** PR_AttachSharedMemory() maps the shared-memory described by
    163 ** shm to the current process.
    164 **
    165 ** INPUTS:
    166 **   shm -- The handle returned from PR_OpenSharedMemory().
    167 **   flags -- options for mapping the shared memory.
    168 **   PR_SHM_READONLY causes the memory to be attached
    169 **   read-only.
    170 **
    171 ** OUTPUTS:
    172 **   On success, the shared memory segment represented by shm is mapped
    173 **   into the process' address space.
    174 **
    175 ** RETURNS: Address where shared memory is mapped, or NULL.
    176 **   NULL is returned on error. The reason for the error can be
    177 **   retrieved via PR_GetError() and PR_GetOSError();
    178 **
    179 **
    180 */
    181 NSPR_API( void * )
    182 PR_AttachSharedMemory(
    183    PRSharedMemory *shm,
    184    PRIntn  flags
    185 );
    186 /* Define values for PR_AttachSharedMemory(...,flags) */
    187 #define PR_SHM_READONLY 0x01
    188 
    189 /*
    190 ** FUNCTION: PR_DetachSharedMemory()
    191 **
    192 ** DESCRIPTION:
    193 **   PR_DetachSharedMemory() detaches the shared-memory described
    194 **   by shm.
    195 **
    196 ** INPUTS:
    197 **   shm -- The handle returned from PR_OpenSharedMemory().
    198 **   addr -- The address at which the memory was attached.
    199 **
    200 ** OUTPUTS:
    201 **   The shared memory mapped to an address via a previous call to
    202 **   PR_AttachSharedMemory() is unmapped.
    203 **
    204 ** RETURNS: PRStatus
    205 **
    206 */
    207 NSPR_API( PRStatus )
    208 PR_DetachSharedMemory(
    209    PRSharedMemory *shm,
    210    void  *addr
    211 );
    212 
    213 /*
    214 ** FUNCTION: PR_CloseSharedMemory()
    215 **
    216 ** DESCRIPTION:
    217 **   PR_CloseSharedMemory() closes the shared-memory described by
    218 **   shm.
    219 **
    220 ** INPUTS:
    221 **   shm -- The handle returned from PR_OpenSharedMemory().
    222 **
    223 ** OUTPUTS:
    224 **   the shared memory represented by shm is closed
    225 **
    226 ** RETURNS: PRStatus
    227 **
    228 */
    229 NSPR_API( PRStatus )
    230 PR_CloseSharedMemory(
    231    PRSharedMemory *shm
    232 );
    233 
    234 /*
    235 ** FUNCTION: PR_DeleteSharedMemory()
    236 **
    237 ** DESCRIPTION:
    238 **   The shared memory resource represented by name is released.
    239 **
    240 ** INPUTS:
    241 **   name -- the name the shared-memory segment
    242 **
    243 ** OUTPUTS:
    244 **   depending on platform, resources may be returned to the underlying
    245 **   operating system.
    246 **
    247 ** RETURNS: PRStatus
    248 **
    249 */
    250 NSPR_API( PRStatus )
    251 PR_DeleteSharedMemory(
    252    const char *name
    253 );
    254 
    255 PR_END_EXTERN_C
    256 
    257 #endif /* prshm_h___ */