Return to prshm.h CVS log

Up to [Synchronet] / sbbs / javascript / include / mozilla / nspr

Annotation of sbbs/javascript/include/mozilla/nspr/prshm.h, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.