PageRenderTime 54ms CodeModel.GetById 30ms app.highlight 4ms RepoModel.GetById 16ms app.codeStats 1ms

/gecko_api/include/prshm.h

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