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() that
45 allows you to use the variable as a normal variable. If a filename is
46 provided, the file is opened and mapped in. If the file is smaller than
47 the length provided, the file is grown to that length. If no filename
48 is provided, anonymous shared inheritable memory is used. Assigning to
49 the variable will replace a section in the file corresponding to the
50 length of the variable, leaving the remainder of the file intact and
51 unmodified. Using substr() allows you to access the file at an offset,
52 and does not place any requirements on the length argument to substr()
53 or the length of the variable being inserted, provided it does not
54 exceed the length of the memory region. This protects you from the
55 pathological cases involved in using mmap() directly, documented below.
56 When calling mmap() or hardwire() directly, you need to be careful how
58 you use the variable. Some programming constructs may create copies of
59 a string which, while unimportant for smallish strings, are far less
60 welcome if you're mapping in a file which is a few gigabytes big. If
61 you use "PROT_WRITE" and attempt to write to the file via the variable
62 you need to be even more careful. One of the few ways in which you can
63 safely write to the string in-place is by using substr() as an lvalue
64 and ensuring that the part of the string that you replace is exactly
65 the same length. Other functions will allocate other storage for the
66 variable, and it will no longer overlay the mapped in file.
67 Sys::Mmap->new( "VARIABLE", "LENGTH", "OPTIONALFILENAME" )
69 Maps "LENGTH" bytes of (the contents of) "OPTIONALFILENAME" if
70 "OPTIONALFILENAME" is provided, otherwise uses anonymous, shared
71 inheritable memory. This memory region is inherited by any fork()ed
72 children. "VARIABLE" will now refer to the contents of that file.
73 Any change to "VARIABLE" will make an identical change to the file.
74 If "LENGTH" is zero and a file is specified, the current length of
75 the file will be used. If "LENGTH" is larger then the file, and
76 "OPTIONALFILENAME" is provided, the file is grown to that length
77 before being mapped. This is the preferred interface, as it
78 requires much less caution in handling the variable. "VARIABLE"
79 will be tied into the "Sys::Mmap" package, and mmap() will be
80 called for you.
81 Assigning to "VARIABLE" will overwrite the beginning of the file
83 for a length of the value being assigned in. The rest of the file
84 or memory region after that point will be left intact. You may use
85 substr() to assign at a given position:
86 substr(VARIABLE, POSITION, LENGTH) = NEWVALUE
88 mmap(VARIABLE, LENGTH, PROTECTION, FLAGS, FILEHANDLE, OFFSET)
90 Maps "LENGTH" bytes of (the underlying contents of) "FILEHANDLE"
91 into your address space, starting at offset "OFFSET" and makes
92 "VARIABLE" refer to that memory. The "OFFSET" argument can be
93 omitted in which case it defaults to zero. The "LENGTH" argument
94 can be zero in which case a stat is done on "FILEHANDLE" and the
95 size of the underlying file is used instead.
96 The "PROTECTION" argument should be some ORed combination of the
98 constants "PROT_READ", "PROT_WRITE" and "PROT_EXEC", or else
99 "PROT_NONE". The constants "PROT_EXEC" and "PROT_NONE" are unlikely
100 to be useful here but are included for completeness.
101 The "FLAGS" argument must include either "MAP_SHARED" or
103 "MAP_PRIVATE" (the latter is unlikely to be useful here). If your
104 platform supports it, you may also use "MAP_ANON" or
105 "MAP_ANONYMOUS". If your platform supplies "MAP_FILE" as a non-
106 zero constant (necessarily non-POSIX) then you should also include
107 that in "FLAGS". POSIX.1b does not specify "MAP_FILE" as a "FLAG"
108 argument and most if not all versions of Unix have "MAP_FILE" as
109 zero.
110 mmap returns "undef" on failure, and the address in memory where
112 the variable was mapped to on success.
113 munmap(VARIABLE)
115 Unmaps the part of your address space which was previously mapped
116 in with a call to "mmap(VARIABLE, ...)" and makes VARIABLE become
117 undefined.
118 munmap returns 1 on success and undef on failure.
120 hardwire(VARIABLE, ADDRESS, LENGTH)
122 Specifies the address in memory of a variable, possibly within a
123 region you've mmap()ed another variable to. You must use the same
124 precautions to keep the variable from being reallocated, and use
125 substr() with an exact length. If you munmap() a region that a
126 hardwire()ed variable lives in, the hardwire()ed variable will not
127 automatically be "undef"ed. You must do this manually.
128 Constants
130 The Sys::Mmap module exports the following constants into your
131 namespace:
132 MAP_SHARED MAP_PRIVATE MAP_ANON MAP_ANONYMOUS MAP_FILE
134 MAP_NORESERVE MAP_POPULATE
135 MAP_HUGETLB MAP_HUGE_2MB MAP_HUGE_1GB
136 PROT_EXEC PROT_NONE PROT_READ PROT_WRITE
137 Of the constants beginning with "MAP_", only "MAP_SHARED" and
139 "MAP_PRIVATE" are defined in POSIX.1b and only "MAP_SHARED" is
140 likely to be useful.
141
143 Scott Walters doesn't know XS, and is just winging it. There must be a
144 better way to tell Perl not to reallocate a variable in memory...
145 The tie() interface makes writing to a substring of the variable much
147 less efficient. One user cited his application running 10-20 times
148 slower when "Sys::Mmap->new()" is used than when mmap() is called
149 directly.
150 Malcolm Beattie has not reviewed Scott's work and is not responsible
152 for any bugs, errors, omissions, stylistic failings, importabilities,
153 or design flaws in this version of the code.
154 There should be a tied interface to hardwire() as well.
156 Scott Walter's spelling is awful.
158 hardwire() will segfault Perl if the mmap() area it was referring to is
160 munmap()'d out from under it.
161 munmap() will segfault Perl if the variable was not successfully
163 mmap()'d previously, or if it has since been reallocated by Perl.
164
166 CowboyTim added support for MAP_NORESERVE, MAP_HUGETLB, MAP_HUGE_2MB,
167 and MAP_HUGE_1GB. Thanks CowboyTim!
168 Todd Rinaldo cleaned up code, modernized again, and merged in many
170 fixes, 2010-2011.
171 Scott Walters updated for Perl 5.6.x, additions, 2002.
173 Malcolm Beattie, 21 June 1996.
175perl v5.38.0 2023-07-21 Mmap(3)