Return to prshma.h CVS log

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

Annotation of sbbs/include/mozilla/nspr/prshma.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: ** prshma.h -- NSPR Anonymous Shared Memory
        !            37: **
        !            38: ** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
        !            39: ** type. The anonymous file-mapped shared memory provides an inheritable
        !            40: ** shared memory, as in: the child process inherits the shared memory.
        !            41: ** Compare the file-mapped anonymous shared memory to to a named shared
        !            42: ** memory described in prshm.h. The intent is to provide a shared
        !            43: ** memory that is accessable only by parent and child processes. ...
        !            44: ** It's a security thing.
        !            45: ** 
        !            46: ** Depending on the underlying platform, the file-mapped shared memory
        !            47: ** may be backed by a file. ... surprise! ... On some platforms, no
        !            48: ** real file backs the shared memory. On platforms where the shared
        !            49: ** memory is backed by a file, the file's name in the filesystem is
        !            50: ** visible to other processes for only the duration of the creation of
        !            51: ** the file, hopefully a very short time. This restricts processess
        !            52: ** that do not inherit the shared memory from opening the file and
        !            53: ** reading or writing its contents. Further, when all processes
        !            54: ** using an anonymous shared memory terminate, the backing file is
        !            55: ** deleted. ... If you are not paranoid, you're not paying attention.
        !            56: ** 
        !            57: ** The file-mapped shared memory requires a protocol for the parent
        !            58: ** process and child process to share the memory. NSPR provides two
        !            59: ** protocols. Use one or the other; don't mix and match.
        !            60: ** 
        !            61: ** In the first protocol, the job of passing the inheritable shared
        !            62: ** memory is done via helper-functions with PR_CreateProcess(). In the
        !            63: ** second protocol, the parent process is responsible for creating the
        !            64: ** child process; the parent and child are mutually responsible for
        !            65: ** passing a FileMap string. NSPR provides helper functions for
        !            66: ** extracting data from the PRFileMap object. ... See the examples
        !            67: ** below.
        !            68: ** 
        !            69: ** Both sides should adhere strictly to the protocol for proper
        !            70: ** operation. The pseudo-code below shows the use of a file-mapped
        !            71: ** shared memory by a parent and child processes. In the examples, the
        !            72: ** server creates the file-mapped shared memory, the client attaches to
        !            73: ** it.
        !            74: **
        !            75: ** First protocol.
        !            76: ** Server:
        !            77: **
        !            78: **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
        !            79: **   addr = PR_MemMap(fm); 
        !            80: **   attr = PR_NewProcessAttr();
        !            81: **   PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
        !            82: **   PR_CreateProcess(Client); 
        !            83: **   PR_DestroyProcessAttr(attr);
        !            84: **   ... yadda ...
        !            85: **   PR_MemUnmap( addr );
        !            86: **   PR_CloseFileMap(fm);
        !            87: **
        !            88: **
        !            89: ** Client: 
        !            90: **   ... started by server via PR_CreateProcess()
        !            91: **   fm = PR_GetInheritedFileMap( shmname );
        !            92: **   addr = PR_MemMap(fm);
        !            93: **   ... yadda ...
        !            94: **   PR_MemUnmap(addr);
        !            95: **   PR_CloseFileMap(fm);
        !            96: **
        !            97: **
        !            98: ** Second Protocol:
        !            99: ** Server:
        !           100: **
        !           101: **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
        !           102: **   fmstring = PR_ExportFileMapAsString( fm );
        !           103: **   addr = PR_MemMap(fm); 
        !           104: **    ... application specific technique to pass fmstring to child
        !           105: **    ... yadda ... Server uses his own magic to create child
        !           106: **   PR_MemUnmap( addr );
        !           107: **   PR_CloseFileMap(fm);
        !           108: **
        !           109: **
        !           110: ** Client: 
        !           111: **   ... started by server via his own magic
        !           112: **   ... application specific technique to find fmstring from parent
        !           113: **   fm = PR_ImportFileMapFromString( fmstring )
        !           114: **   addr = PR_MemMap(fm);
        !           115: **   ... yadda ...
        !           116: **   PR_MemUnmap(addr);
        !           117: **   PR_CloseFileMap(fm);
        !           118: **
        !           119: **
        !           120: ** lth. 2-Jul-1999.
        !           121: **
        !           122: ** Note: The second protocol was requested by NelsonB (7/1999); this is
        !           123: ** to accomodate servers which already create their own child processes
        !           124: ** using platform native methods.
        !           125: ** 
        !           126: */
        !           127: 
        !           128: #ifndef prshma_h___
        !           129: #define prshma_h___
        !           130: 
        !           131: #include "prtypes.h"
        !           132: #include "prio.h"
        !           133: #include "prproces.h"
        !           134: 
        !           135: PR_BEGIN_EXTERN_C
        !           136: 
        !           137: /*
        !           138: ** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
        !           139: **
        !           140: ** Description:
        !           141: ** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
        !           142: ** shared memory already exists, a handle is returned to that shared
        !           143: ** memory object.
        !           144: **
        !           145: ** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
        !           146: ** directory name, without the trailing '/', to contain the anonymous
        !           147: ** file. A filename is generated for the name.
        !           148: **
        !           149: ** On Windows platforms, dirName is ignored.
        !           150: **
        !           151: ** Inputs:
        !           152: **   dirName -- A directory name to contain the anonymous file.
        !           153: **   size -- The size of the shared memory
        !           154: **   prot -- How the shared memory is mapped. See prio.h
        !           155: **   
        !           156: ** Outputs:
        !           157: **   PRFileMap *
        !           158: **
        !           159: ** Returns:
        !           160: **   Pointer to PRFileMap or NULL on error.
        !           161: **
        !           162: */
        !           163: NSPR_API( PRFileMap *)
        !           164: PR_OpenAnonFileMap(
        !           165:     const char *dirName,
        !           166:     PRSize      size, 
        !           167:     PRFileMapProtect prot
        !           168: );  
        !           169: 
        !           170: /*
        !           171: ** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export  
        !           172: **   to my children processes via PR_CreateProcess()
        !           173: **
        !           174: ** Description:
        !           175: ** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
        !           176: ** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
        !           177: ** makes the PRFileMap importable by the child process.
        !           178: **
        !           179: ** Inputs:
        !           180: **   attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
        !           181: **   fm -- PRFileMap structure to be passed to the child process
        !           182: **   shmname -- The name for the PRFileMap; used by child.
        !           183: **
        !           184: ** Outputs:
        !           185: **   PRFileMap *
        !           186: **
        !           187: ** Returns:
        !           188: **   PRStatus
        !           189: **
        !           190: */
        !           191: NSPR_API(PRStatus) 
        !           192: PR_ProcessAttrSetInheritableFileMap( 
        !           193:     PRProcessAttr   *attr,
        !           194:     PRFileMap       *fm, 
        !           195:     const char      *shmname
        !           196: );
        !           197: 
        !           198: /*
        !           199: ** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
        !           200: **   by my parent process via PR_CreateProcess()
        !           201: **
        !           202: ** Description:
        !           203: ** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
        !           204: ** its parent process via PR_CreateProcess().
        !           205: **
        !           206: ** Inputs:
        !           207: **    shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
        !           208: ** 
        !           209: ** Outputs:
        !           210: **   PRFileMap *
        !           211: **
        !           212: ** Returns:
        !           213: **   PRFileMap pointer or NULL.
        !           214: **
        !           215: */
        !           216: NSPR_API( PRFileMap *)
        !           217: PR_GetInheritedFileMap( 
        !           218:     const char *shmname 
        !           219: );
        !           220: 
        !           221: /*
        !           222: ** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
        !           223: **
        !           224: ** Description:
        !           225: ** Creates an identifier, as a string, from a PRFileMap object
        !           226: ** previously created with PR_OpenAnonFileMap().
        !           227: **
        !           228: ** Inputs:
        !           229: **   fm -- PRFileMap pointer to be represented as a string.
        !           230: **   bufsize -- sizeof(buf)
        !           231: **   buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
        !           232: **
        !           233: ** Outputs:
        !           234: **   buf contains the stringized PRFileMap identifier
        !           235: **
        !           236: ** Returns:
        !           237: **   PRStatus
        !           238: **
        !           239: */
        !           240: NSPR_API( PRStatus )
        !           241: PR_ExportFileMapAsString( 
        !           242:     PRFileMap *fm,
        !           243:     PRSize    bufsize,
        !           244:     char      *buf
        !           245: );
        !           246: #define PR_FILEMAP_STRING_BUFSIZE 128
        !           247: 
        !           248: /*
        !           249: ** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
        !           250: **
        !           251: ** Description:
        !           252: ** PR_ImportFileMapFromString() creates a PRFileMap object from a
        !           253: ** string previously created by PR_ExportFileMapAsString().
        !           254: **
        !           255: ** Inputs:
        !           256: **   fmstring -- string created by PR_ExportFileMapAsString()
        !           257: **
        !           258: ** Returns:
        !           259: **   PRFileMap pointer or NULL.
        !           260: **
        !           261: */
        !           262: NSPR_API( PRFileMap * )
        !           263: PR_ImportFileMapFromString( 
        !           264:     const char *fmstring
        !           265: );
        !           266: 
        !           267: PR_END_EXTERN_C
        !           268: #endif /* prshma_h___ */

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