<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>IPC::Mmap</title>
<link rel="stylesheet" type="text/css" href="../podstyle.css" /><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<div class="box">
<h1 class="t1">IPC::Mmap</h1>
<table>
<tr>
<td class="label">Description</td>
<td class="cell">minimal mmap() for POSIX and Win32 platforms</td>
</tr>
</table>
</div>
<div class="path">
<a href="../index.html">IPC::Mmap</a> > Package Manuals >
IPC-Mmap
</div>
<div>
<a href="Mmap.html">Classdocs</a>
</div>
<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>
<ul>
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a></li>
<li><a href="#Constants">Constants</a></li>
<li><a href="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</a></li>
<li><a href="#SEE_ALSO">SEE ALSO</a></li>
<li><a href="#AUTHOR_COPYRIGHT_AND_LICENSE">AUTHOR, COPYRIGHT, AND LICENSE</a></li>
</ul>
<hr />
<!-- INDEX END -->
<h1 id="NAME">NAME <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>IPC::Mmap - provides a minimal mmap() interface for both POSIX and Win32</p>
<h1 id="SYNOPSIS">SYNOPSIS <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<pre> use IPC::Mmap;
#
# create from opened filehandle
#
$mmap_by_handle = IPC::Mmap->new(FILEHANDLE, 8192, PROT_READ|PROT_WRITE, MAP_SHARED)
or die $!;
#
# create from filename
#
$mmap_by_name = IPC::Mmap->new('somefile.dat', 8192, PROT_READ|PROT_WRITE, MAP_SHARED)
or die $!;
#
# write some data to a specific position
#
my $writelen = $mmap_by_name->write($value, $offset, $len);
#
# read it back somewhere else
#
my $data;
my $readlen = $mmap_by_handle->read($data, $offset, $len);
#
# lock for read before reading
#
$mmap_by_handle->lock(LOCK_EX);
my $len = $mmap_by_handle->read($data, $offset, $len);
$mmap_by_handle->unlock();
#
# convenient binary pack/unpack
#
my $len = $mmap_by_name->pack($offset, 'lldV', $this, $this, $float, $other);
($this, $this, $float, $other) = $mmap_by_name->unpack($offset, 24, 'lldV');
#
# when done, unmap
#
$mmap_from_name->unmap();
</pre><h1 id="DESCRIPTION">DESCRIPTION <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Provides an object-oriented interface to either the POSIX <code>mmap()</code> or
Win32 equivalent APIs to memory map a file into a process's address space for
general memory access. IPC::Mmap provides only a minimal
interface without the additional overhead of <a href="http://search.cpan.org/perldoc?tie">tie</a>'d variables or
locking enforced in other modules (e.g., <a href="http://search.cpan.org/perldoc?Sys%3A%3AMmap">Sys::Mmap</a>, <a href="http://search.cpan.org/perldoc?Win32%3A%3AMMF">Win32::MMF</a>);
hence, the application is responsible for performing <code>read()</code>'s
and <code>write()</code>'s on the IPC::Mmap object, and calling any needed
<code>lock()</code> and <code>unlock()</code> methods, as required by concurrent processes.</p>
<p>Memory mapped files provide an alternate shared memory mechanism
for multiple processes. The technique maps the OS's file system
buffers for a given file into each <code>mmap()</code>'ing process's virtual
memory space, thereby permitting each process to essentially share
the same physical memory. <i>Refer to the excellent "Advanced Programming
in the UNIX Environment", Stevens et al., Addison-Wesley Publisher
for a detailed reference on the POSIX implementation.</i>
<a href="Mmap.pm.html">IPC::Mmap</a> provides OS-agnostic wrappers for both the POSIX and Win32
memory mapped file capabilities.</p>
<p><strong>Note</strong> that <a href="http://search.cpan.org/perldoc?PerlIO">PerlIO</a> provides a <code>:mmap</code> layer to permit <strong>read-only</strong> access
to mmap'd files as regular files.</p>
<h1 id="METHODS">METHODS <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Refer to the included classdocs for summary and detailed method
descriptions.</p>
<h1 id="Constants">Constants <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>IPC::Mmap exports the following constants into your namespace:</p>
<pre> MAP_SHARED MAP_PRIVATE MAP_ANON MAP_ANONYMOUS MAP_FILE
PROT_READ PROT_WRITE
</pre><p>Of the constants beginning with MAP_, only MAP_SHARED and MAP_PRIVATE are
defined in POSIX.1b and only MAP_SHARED is likely to be useful.</p>
<p>Note that PROT_EXEC and PROT_NONE are not exported, nor supported.</p>
<p>These POSIX values are mapped into Win32 equivalents internally
where appropriate.</p>
<h1 id="ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Much of the POSIX XS code was borrowed from <a href="http://search.cpan.org/perldoc?Sys%3A%3AMmap">Sys::Mmap</a>.
Likewise, much of the Win32 implementation is borrowed from
<a href="http://search.cpan.org/perldoc?Win32%3A%3AMMF">Win32::MMF</a>.</p>
<h1 id="SEE_ALSO">SEE ALSO <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p><a href="http://search.cpan.org/perldoc?Sys%3A%3AMmap">Sys::Mmap</a></p>
<p><a href="http://search.cpan.org/perldoc?Win32%3A%3AMMF">Win32::MMF</a></p>
<p>mmap(1) <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html">http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html</a></p>
<h1 id="AUTHOR_COPYRIGHT_AND_LICENSE">AUTHOR, COPYRIGHT, AND LICENSE <a href="#TOP" class="toplink"><img alt="^" src="../up.gif" /></a></h1>
<p>Dean Arnold <a href="mailto:darnold@presicient.com">mailto:darnold@presicient.com</a></p>
<p>Copyright(C) 2006, Dean Arnold, Presicient Corp., USA.
All rights reserved.</p>
<p>Permission is granted to use this software under the same terms as Perl itself.
Refer to the <a href="http://search.cpan.org/perldoc?perlartistic">Perl Artistic License</a> for details.</p>
</div><div class="footer">generated by <a href="http://search.cpan.org/perldoc?Pod%3A%3AProjectDocs">Pod::ProjectDocs</a></div></body>
</html>