prshma.h

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- *//* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Netscape Portable Runtime (NSPR). * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1999-2000 * the Initial Developer. All Rights Reserved. * * Contributor(s): * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** *//*** prshma.h -- NSPR Anonymous Shared Memory**** NSPR provides an anonymous shared memory based on NSPR's PRFileMap** type. The anonymous file-mapped shared memory provides an inheritable** shared memory, as in: the child process inherits the shared memory.** Compare the file-mapped anonymous shared memory to to a named shared** memory described in prshm.h. The intent is to provide a shared** memory that is accessable only by parent and child processes. ...** It's a security thing.** ** Depending on the underlying platform, the file-mapped shared memory** may be backed by a file. ... surprise! ... On some platforms, no** real file backs the shared memory. On platforms where the shared** memory is backed by a file, the file's name in the filesystem is** visible to other processes for only the duration of the creation of** the file, hopefully a very short time. This restricts processess** that do not inherit the shared memory from opening the file and** reading or writing its contents. Further, when all processes** using an anonymous shared memory terminate, the backing file is** deleted. ... If you are not paranoid, you're not paying attention.** ** The file-mapped shared memory requires a protocol for the parent** process and child process to share the memory. NSPR provides two** protocols. Use one or the other; don't mix and match.** ** In the first protocol, the job of passing the inheritable shared** memory is done via helper-functions with PR_CreateProcess(). In the** second protocol, the parent process is responsible for creating the** child process; the parent and child are mutually responsible for** passing a FileMap string. NSPR provides helper functions for** extracting data from the PRFileMap object. ... See the examples** below.** ** Both sides should adhere strictly to the protocol for proper** operation. The pseudo-code below shows the use of a file-mapped** shared memory by a parent and child processes. In the examples, the** server creates the file-mapped shared memory, the client attaches to** it.**** First protocol.** Server:**** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); ** addr = PR_MemMap(fm); ** attr = PR_NewProcessAttr();** PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );** PR_CreateProcess(Client); ** PR_DestroyProcessAttr(attr);** ... yadda ...** PR_MemUnmap( addr );** PR_CloseFileMap(fm);****** Client: ** ... started by server via PR_CreateProcess()** fm = PR_GetInheritedFileMap( shmname );** addr = PR_MemMap(fm);** ... yadda ...** PR_MemUnmap(addr);** PR_CloseFileMap(fm);****** Second Protocol:** Server:**** fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); ** fmstring = PR_ExportFileMapAsString( fm );** addr = PR_MemMap(fm); ** ... application specific technique to pass fmstring to child** ... yadda ... Server uses his own magic to create child** PR_MemUnmap( addr );** PR_CloseFileMap(fm);****** Client: ** ... started by server via his own magic** ... application specific technique to find fmstring from parent** fm = PR_ImportFileMapFromString( fmstring )** addr = PR_MemMap(fm);** ... yadda ...** PR_MemUnmap(addr);** PR_CloseFileMap(fm);****** lth. 2-Jul-1999.**** Note: The second protocol was requested by NelsonB (7/1999); this is** to accomodate servers which already create their own child processes** using platform native methods.** */#ifndef prshma_h___#define prshma_h___#include "prtypes.h"#include "prio.h"#include "prproces.h"
PR_BEGIN_EXTERN_C
/*** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory**** Description:** PR_OpenAnonFileMap() creates an anonymous shared memory. If the** shared memory already exists, a handle is returned to that shared** memory object.**** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a** directory name, without the trailing '/', to contain the anonymous** file. A filename is generated for the name.**** On Windows platforms, dirName is ignored.**** Inputs:** dirName -- A directory name to contain the anonymous file.** size -- The size of the shared memory** prot -- How the shared memory is mapped. See prio.h** ** Outputs:** PRFileMap ***** Returns:** Pointer to PRFileMap or NULL on error.***/
NSPR_API( PRFileMap *)
PR_OpenAnonFileMap(
const char *dirName,
PRSize size,
PRFileMapProtect prot
);
/*** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export ** to my children processes via PR_CreateProcess()**** Description:** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()** makes the PRFileMap importable by the child process.**** Inputs:** attr -- PRProcessAttr, used to pass data to PR_CreateProcess()** fm -- PRFileMap structure to be passed to the child process** shmname -- The name for the PRFileMap; used by child.**** Outputs:** PRFileMap ***** Returns:** PRStatus***/
NSPR_API(PRStatus)
PR_ProcessAttrSetInheritableFileMap(
PRProcessAttr *attr,
PRFileMap *fm,
const char *shmname
);
/*** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported** by my parent process via PR_CreateProcess()**** Description:** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from** its parent process via PR_CreateProcess().**** Inputs:** shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()** ** Outputs:** PRFileMap ***** Returns:** PRFileMap pointer or NULL.***/
NSPR_API( PRFileMap *)
PR_GetInheritedFileMap(
const char *shmname
);
/*** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap**** Description:** Creates an identifier, as a string, from a PRFileMap object** previously created with PR_OpenAnonFileMap().**** Inputs:** fm -- PRFileMap pointer to be represented as a string.** bufsize -- sizeof(buf)** buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE**** Outputs:** buf contains the stringized PRFileMap identifier**** Returns:** PRStatus***/
NSPR_API( PRStatus )
PR_ExportFileMapAsString(
PRFileMap *fm,
PRSize bufsize,
char *buf
);
#define PR_FILEMAP_STRING_BUFSIZE 128/*** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string**** Description:** PR_ImportFileMapFromString() creates a PRFileMap object from a** string previously created by PR_ExportFileMapAsString().**** Inputs:** fmstring -- string created by PR_ExportFileMapAsString()**** Returns:** PRFileMap pointer or NULL.***/
NSPR_API( PRFileMap * )
PR_ImportFileMapFromString(
const char *fmstring
);
PR_END_EXTERN_C
#endif /* prshma_h___ */