.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mmap 3"
.TH Mmap 3 "2014-08-23" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sys::Mmap \- uses mmap to map in a file as a Perl variable
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Sys::Mmap;
\&
\&    new Mmap $str, 8192, \*(Aqstructtest2.pl\*(Aq or die $!;
\&    new Mmap $var, 8192 or die $!;
\&
\&    mmap($foo, 0, PROT_READ, MAP_SHARED, FILEHANDLE) or die "mmap: $!";
\&    @tags = $foo =~ /<(.*?)>/g;
\&    munmap($foo) or die "munmap: $!";
\&    
\&    mmap($bar, 8192, PROT_READ|PROT_WRITE, MAP_SHARED, FILEHANDLE);
\&    substr($bar, 1024, 11) = "Hello world";
\&
\&    mmap($baz, 8192, PROT_READ|PROT_WRITE, MAP_SHARED|MAP_ANON, STDOUT);
\&
\&    $addr = mmap($baz, 8192, PROT_READ|PROT_WRITE, MAP_SHARED|MAP_ANON, STDOUT);
\&    Sys::Mmap::hardwire($qux, $addr, 8192);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Mmap module uses the \s-1POSIX \s0mmap call to map in a file as a Perl variable.
Memory access by mmap may be shared between threads or forked processes, and
may be a disc file that has been mapped into memory.
Sys::Mmap depends on your operating system supporting \s-1UNIX\s0 or \s-1POSIX\s0.1b mmap, of
course.
.PP
\&\fBNote\fR that PerlIO now defines a \f(CW\*(C`:mmap\*(C'\fR tag and presents mmap'd files
as regular files, if that is your cup of joe.
.PP
Several processes may share one copy
of the file or string, saving memory, and concurrently making changes to 
portions of the file or string. When not used with a file, it is an
alternative to SysV shared memory. Unlike SysV shared memory, there 
are no arbitrary size limits on
the shared memory area, and sparce memory usage is handled optimally on
most modern \s-1UNIX\s0 implementations.
.PP
Using the \f(CW\*(C`new()\*(C'\fR method provides a \f(CW\*(C`tie()\*(C'\fR'd interface to \f(CW\*(C`mmap()\*(C'\fR that
allows you to use the variable as a normal variable. If a filename
is provided, the file is opened and mapped in. If the file is
smaller than the length provided, the file is grown to that length.
If no filename is
provided, anonymous shared inheritable memory is used. Assigning to
the variable will replace a section in the file corresponding to
the length of the variable, leaving the remainder of the file 
intact and unmodified. Using \f(CW\*(C`substr()\*(C'\fR allows you to access 
the file at an offset, and does not place any requirements on
the length argument to \fIsubstr()\fR or the length of the variable
being inserted, provided it does not exceed the length of the
memory region. This protects you from the pathological cases
involved in using \f(CW\*(C`mmap()\*(C'\fR directly, documented below.
.PP
When calling \f(CW\*(C`mmap()\*(C'\fR or \f(CW\*(C`hardwire()\*(C'\fR directly,
you need to be careful how you use the variable. Some
programming constructs may create copies of a string which, while
unimportant for smallish strings, are far less welcome if you're
mapping in a file which is a few gigabytes big. If you use \s-1PROT_WRITE\s0
and attempt to write to the file via the variable you need to be even
more careful. One of the few ways in which you can safely write to
the string in-place is by using \f(CW\*(C`substr()\*(C'\fR as an lvalue and ensuring that
the part of the string that you replace is exactly the same length.
Other functions will allocate other storage for the variable,
and it will no longer overlay the mapped in file.
.IP "new Mmap \s-1VARIABLE, LENGTH, OPTIONALFILENAME\s0" 4
.IX Item "new Mmap VARIABLE, LENGTH, OPTIONALFILENAME"
Maps \s-1LENGTH\s0 bytes of (the contents of) \s-1OPTIONALFILENAME\s0 if
\&\s-1OPTINALFILENAME\s0 is provided, otherwise uses anonymous, shared
inheritable memory. This memory region is inherited by any \f(CW\*(C`fork()\*(C'\fRed
children. \s-1VARIABLE\s0 will now refer to the contents of that file.
Any change to \s-1VARIABLE\s0 will make an identical change to the file.
If \s-1LENGTH\s0 is zero and a file is specified, the current length of the
file will be used.
If \s-1LENGTH\s0 is larger then the file, and \s-1OPTIONALFILENAME\s0 is
provided, the file is grown to that length before being mapped.
This is the preferred interface, as it requires much less caution
in handling the variable. \s-1VARIABLE\s0 will be tied into the \*(L"Mmap\*(R"
package, and \f(CW\*(C`mmap()\*(C'\fR will be called for you.
.Sp
Assigning to \s-1VARIABLE\s0 will overwrite the beginning of the file
for a length of the value being assigned in. The rest of the
file or memory region after that point will be left intact.
You may use \fIsubstr()\fR to assign at a given position:
.Sp
substr(\s-1VARIABLE, POSITION, LENGTH\s0) = \s-1NEWVALUE\s0
.IP "mmap(\s-1VARIABLE, LENGTH, PROTECTION, FLAGS, FILEHANDLE, OFFSET\s0)" 4
.IX Item "mmap(VARIABLE, LENGTH, PROTECTION, FLAGS, FILEHANDLE, OFFSET)"
Maps \s-1LENGTH\s0 bytes of (the underlying contents of) \s-1FILEHANDLE\s0 into your
address space, starting at offset \s-1OFFSET\s0 and makes \s-1VARIABLE\s0 refer to
that memory. The \s-1OFFSET\s0 argument can be omitted in which case it defaults
to zero. The \s-1LENGTH\s0 argument can be zero in which case a stat is done on
\&\s-1FILEHANDLE\s0 and the size of the underlying file is used instead.
.Sp
The \s-1PROTECTION\s0 argument should be some ORed combination of the
constants \s-1PROT_READ, PROT_WRITE\s0 and \s-1PROT_EXEC\s0 or else \s-1PROT_NONE.\s0 The
constants \s-1PROT_EXEC\s0 and \s-1PROT_NONE\s0 are unlikely to be useful here but are
included for completeness.
.Sp
The \s-1FLAGS\s0 argument must include either
\&\s-1MAP_SHARED\s0 or \s-1MAP_PRIVATE \s0(the latter is unlikely to be useful here).
If your platform supports it, you may also use \s-1MAP_ANON\s0 or \s-1MAP_ANONYMOUS.\s0
If your platform supplies \s-1MAP_FILE\s0 as a non-zero constant (necessarily
non-POSIX) then you should also include that in \s-1FLAGS. POSIX\s0.1b does not
specify \s-1MAP_FILE\s0 as a \s-1FLAG\s0 argument and most if not all versions of Unix
have \s-1MAP_FILE\s0 as zero.
.Sp
mmap returns undef on failure, and the address in memory where the
variable was mapped to on success.
.IP "munmap(\s-1VARIABLE\s0)" 4
.IX Item "munmap(VARIABLE)"
Unmaps the part of your address space which was previously mapped in
with a call to \f(CW\*(C`mmap(VARIABLE, ...)\*(C'\fR and makes \s-1VARIABLE\s0 become undefined.
.Sp
munmap returns 1 on success and undef on failure.
.IP "hardwire(\s-1VARIABLE, ADDRESS, LENGTH\s0)" 4
.IX Item "hardwire(VARIABLE, ADDRESS, LENGTH)"
Specifies the address in memory of a variable, possibly within a
region you've \f(CW\*(C`mmap()\*(C'\fRed another variable to. You must use the
same percaustions to keep the variable from being reallocated,
and use \f(CW\*(C`substr()\*(C'\fR with an exact length. If you \f(CW\*(C`munmap()\*(C'\fR a
region that a \f(CW\*(C`hardwire()\*(C'\fRed variable lives in, the \f(CW\*(C`hardwire()\*(C'\fRed
variable will not automatically be \f(CW\*(C`undef\*(C'\fRed. You must do this
manually.
.IP "Constants" 4
.IX Item "Constants"
The Mmap module exports the following constants into your namespace
    \s-1MAP_SHARED MAP_PRIVATE MAP_ANON MAP_ANONYMOUS MAP_FILE
    PROT_EXEC PROT_NONE PROT_READ PROT_WRITE\s0
.Sp
Of the constants beginning \s-1MAP_,\s0 only \s-1MAP_SHARED\s0 and \s-1MAP_PRIVATE\s0 are
defined in \s-1POSIX\s0.1b and only \s-1MAP_SHARED\s0 is likely to be useful.
.SH "BUGS"
.IX Header "BUGS"
Scott Walters doesn't know \s-1XS,\s0 and is just winging it. There must be a
better way to tell Perl not to reallocate a variable in memory...
.PP
The \fItie()\fR interface makes writing to a substring of the variable
much less efficient.  One user cited his application running 10\-20 times slower when 
\&\*(L"new Mmap\*(R" is used than when \fImmap()\fR is called directly.
.PP
Malcolm Beattie has not reviewed Scott's work and is not responsible for any
bugs, errors, omissions, stylistic failings, importabilities, or design flaws
in this version of the code.
.PP
There should be a tied interface to \fIhardwire()\fR as well.
.PP
Scott Walter's spelling is awful.
.PP
\&\fIhardwire()\fR will segfault Perl if the \fImmap()\fR area it was
refering to is \fImunmap()\fR'd out from under it.
.PP
\&\fImunmap()\fR will segfault Perl if the variable was not successfully
\&\fImmap()\fR'd previously, or if it has since been reallocated by Perl.
.SH "AUTHOR"
.IX Header "AUTHOR"
Todd Rinaldo cleaned up code, modernized again, and merged in many fixes, 2010\-2011.
.PP
Scott Walters updated for Perl 5.6.x, additions, 2002.
.PP
Malcolm Beattie, 21 June 1996.