1Mmap(3) User Contributed Perl Documentation Mmap(3)
2
6 Sys::Mmap - uses mmap to map in a file as a Perl variable
7
9 use Sys::Mmap;
10 Sys::Mmap->new( my $str, 8192, 'structtest2.pl' ) or die $!;
12 Sys::Mmap->new( $var, 8192 ) or die $!;
13 mmap( $foo, 0, PROT_READ, MAP_SHARED, FILEHANDLE ) or die "mmap: $!";
15 @tags = $foo =~ /<(.*?)>/g;
16 munmap($foo) or die "munmap: $!";
17 mmap( $bar, 8192, PROT_READ | PROT_WRITE, MAP_SHARED, FILEHANDLE );
19 substr( $bar, 1024, 11 ) = "Hello world";
20 mmap( $baz, 8192, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANON, STDOUT );
22 $addr = mmap( $baz, 8192, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANON, STDOUT );
24 Sys::Mmap::hardwire( $qux, $addr, 8192 );
25
27 The Sys::Mmap module uses the POSIX mmap
28 <https://en.wikipedia.org/wiki/Mmap> call to map in a file as a Perl
29 variable. Memory access by mmap may be shared between threads or
30 forked processes, and may be a disc file that has been mapped into
31 memory. Sys::Mmap depends on your operating system supporting UNIX or
32 POSIX.1b mmap, of course.
33 Note that PerlIO now defines a ":mmap" tag and presents mmap'd files as
35 regular files, if that is your cup of joe.
36 Several processes may share one copy of the file or string, saving
38 memory, and concurrently making changes to portions of the file or
39 string. When not used with a file, it is an alternative to SysV shared
40 memory. Unlike SysV shared memory, there are no arbitrary size limits
41 on the shared memory area, and sparse memory usage is handled optimally
42 on most modern UNIX implementations.
43 Using the "new()" method provides a "tie()"'d interface to "mmap()"
45 that allows you to use the variable as a normal variable. If a filename
46 is provided, the file is opened and mapped in. If the file is smaller
47 than the length provided, the file is grown to that length. If no
48 filename is provided, anonymous shared inheritable memory is used.
49 Assigning to the variable will replace a section in the file
50 corresponding to the length of the variable, leaving the remainder of
51 the file intact and unmodified. Using "substr()" allows you to access
52 the file at an offset, and does not place any requirements on the
53 length argument to "substr()" or the length of the variable being
54 inserted, provided it does not exceed the length of the memory region.
55 This protects you from the pathological cases involved in using
56 "mmap()" directly, documented below.
57 When calling "mmap()" or "hardwire()" directly, you need to be careful
59 how you use the variable. Some programming constructs may create copies
60 of a string which, while unimportant for smallish strings, are far less
61 welcome if you're mapping in a file which is a few gigabytes big. If
62 you use "PROT_WRITE" and attempt to write to the file via the variable
63 you need to be even more careful. One of the few ways in which you can
64 safely write to the string in-place is by using "substr()" as an lvalue
65 and ensuring that the part of the string that you replace is exactly
66 the same length. Other functions will allocate other storage for the
67 variable, and it will no longer overlay the mapped in file.
68 Sys::Mmap->new( "VARIABLE", "LENGTH", "OPTIONALFILENAME" )
70 Maps "LENGTH" bytes of (the contents of) "OPTIONALFILENAME" if
71 "OPTIONALFILENAME" is provided, otherwise uses anonymous, shared
72 inheritable memory. This memory region is inherited by any
73 "fork()"ed children. "VARIABLE" will now refer to the contents of
74 that file. Any change to "VARIABLE" will make an identical change
75 to the file. If "LENGTH" is zero and a file is specified, the
76 current length of the file will be used. If "LENGTH" is larger
77 then the file, and "OPTIONALFILENAME" is provided, the file is
78 grown to that length before being mapped. This is the preferred
79 interface, as it requires much less caution in handling the
80 variable. "VARIABLE" will be tied into the "Sys::Mmap" package,
81 and "mmap()" will be called for you.
82 Assigning to "VARIABLE" will overwrite the beginning of the file
84 for a length of the value being assigned in. The rest of the file
85 or memory region after that point will be left intact. You may use
86 "substr()" to assign at a given position:
87 substr(VARIABLE, POSITION, LENGTH) = NEWVALUE
89 mmap(VARIABLE, LENGTH, PROTECTION, FLAGS, FILEHANDLE, OFFSET)
91 Maps "LENGTH" bytes of (the underlying contents of) "FILEHANDLE"
92 into your address space, starting at offset "OFFSET" and makes
93 "VARIABLE" refer to that memory. The "OFFSET" argument can be
94 omitted in which case it defaults to zero. The "LENGTH" argument
95 can be zero in which case a stat is done on "FILEHANDLE" and the
96 size of the underlying file is used instead.
97 The "PROTECTION" argument should be some ORed combination of the
99 constants "PROT_READ", "PROT_WRITE" and "PROT_EXEC", or else
100 "PROT_NONE". The constants "PROT_EXEC" and "PROT_NONE" are unlikely
101 to be useful here but are included for completeness.
102 The "FLAGS" argument must include either "MAP_SHARED" or
104 "MAP_PRIVATE" (the latter is unlikely to be useful here). If your
105 platform supports it, you may also use "MAP_ANON" or
106 "MAP_ANONYMOUS". If your platform supplies "MAP_FILE" as a non-
107 zero constant (necessarily non-POSIX) then you should also include
108 that in "FLAGS". POSIX.1b does not specify "MAP_FILE" as a "FLAG"
109 argument and most if not all versions of Unix have "MAP_FILE" as
110 zero.
111 mmap returns "undef" on failure, and the address in memory where
113 the variable was mapped to on success.
114 munmap(VARIABLE)
116 Unmaps the part of your address space which was previously mapped
117 in with a call to "mmap(VARIABLE, ...)" and makes VARIABLE become
118 undefined.
119 munmap returns 1 on success and undef on failure.
121 hardwire(VARIABLE, ADDRESS, LENGTH)
123 Specifies the address in memory of a variable, possibly within a
124 region you've "mmap()"ed another variable to. You must use the same
125 precautions to keep the variable from being reallocated, and use
126 "substr()" with an exact length. If you "munmap()" a region that a
127 "hardwire()"ed variable lives in, the "hardwire()"ed variable will
128 not automatically be "undef"ed. You must do this manually.
129 Constants
131 The Sys::Mmap module exports the following constants into your
132 namespace:
133 MAP_SHARED MAP_PRIVATE MAP_ANON MAP_ANONYMOUS MAP_FILE
135 MAP_NORESERVE MAP_POPULATE
136 MAP_HUGETLB MAP_HUGE_2MB MAP_HUGE_1GB
137 PROT_EXEC PROT_NONE PROT_READ PROT_WRITE
138 Of the constants beginning with "MAP_", only "MAP_SHARED" and
140 "MAP_PRIVATE" are defined in POSIX.1b and only "MAP_SHARED" is
141 likely to be useful.
142
144 Scott Walters doesn't know XS, and is just winging it. There must be a
145 better way to tell Perl not to reallocate a variable in memory...
146 The "tie()" interface makes writing to a substring of the variable much
148 less efficient. One user cited his application running 10-20 times
149 slower when "Sys::Mmap->new()" is used than when "mmap()" is called
150 directly.
151 Malcolm Beattie has not reviewed Scott's work and is not responsible
153 for any bugs, errors, omissions, stylistic failings, importabilities,
154 or design flaws in this version of the code.
155 There should be a tied interface to "hardwire()" as well.
157 Scott Walter's spelling is awful.
159 "hardwire()" will segfault Perl if the "mmap()" area it was referring
161 to is "munmap()"'d out from under it.
162 "munmap()" will segfault Perl if the variable was not successfully
164 "mmap()"'d previously, or if it has since been reallocated by Perl.
165
167 CowboyTim added support for MAP_NORESERVE, MAP_HUGETLB, MAP_HUGE_2MB,
168 and MAP_HUGE_1GB. Thanks CowboyTim!
169 Todd Rinaldo cleaned up code, modernized again, and merged in many
171 fixes, 2010-2011.
172 Scott Walters updated for Perl 5.6.x, additions, 2002.
174 Malcolm Beattie, 21 June 1996.
176perl v5.32.0 2020-07-28 Mmap(3)