View on
Leon Timmermans > File-Map > File::Map



Annotate this POD


New  2
Open  0
View/Report Bugs
Module Version: 0.64   Source  


File::Map - Memory mapping made simple and safe.


version 0.64


 use File::Map 'map_file';
 map_file my $map, $filename, '+<';
 $map =~ s/bar/quz/g;
 substr $map, 1024, 11, "Hello world";


File::Map maps files or anonymous memory into perl variables.

Advantages of memory mapping

Advantages of this module over other similar modules



The following functions for mapping a variable are available for exportation. Note that all of these functions throw exceptions on errors, unless noted otherwise.

map_handle $lvalue, $filehandle, $mode = '<', $offset = 0, $length = -s(*handle) - $offset

Use a filehandle to map into an lvalue. $filehandle should be a scalar filehandle. $mode uses the same format as open does (it currently accepts <, +<, > and +>). $offset and $length are byte positions in the file, and default to mapping the whole file.

* map_file $lvalue, $filename, $mode = '<', $offset = 0, $length = -s($filename) - $offset

Open a file and map it into an lvalue. Other than $filename, all arguments work as in map_handle.

* map_anonymous $lvalue, $length, $type

Map an anonymous piece of memory. $type can be either 'shared', in which case it will be shared with child processes, or 'private', which won't be shared.

* sys_map $lvalue, $length, $protection, $flags, $filehandle, $offset = 0

Low level map operation. It accepts the same constants as mmap does (except its first argument obviously). If you don't know how mmap works you probably shouldn't be using this.

* unmap $lvalue

Unmap a variable. Note that normally this is not necessary as variables are unmapped automatically at destruction, but it is included for completeness.

* remap $lvalue, $new_size

Try to remap $lvalue to a new size. This call is linux specific and not supported on other systems. For a file backed mapping a file must be long enough to hold the new size, otherwise you can expect bus faults. For an anonymous map it must be private, shared maps can not be remapped. Use with caution.


* sync $lvalue, $synchronous = 1

Flush changes made to the memory map back to disk. Mappings are always flushed when unmapped, so this is usually not necessary. If $synchronous is true and your operating system supports it, the flushing will be done synchronously.

* pin $lvalue

Disable paging for this map, thus locking it in physical memory. Depending on your operating system there may be limits on pinning.

* unpin $lvalue

Unlock the map from physical memory.

* advise $lvalue, $advice

Advise a certain memory usage pattern. This is not implemented on all operating systems, and may be a no-op. The following values for $advice are always accepted:.

On some systems there may be more values available, but this can not be relied on. Unknown values for $advice will cause a warning but are further ignored.

* protect $lvalue, $mode

Change the memory protection of the mapping. $mode takes the same format as, but also accepts sys_map style constants.


These locking functions provide locking for threads for the mapped region. The mapped region has an internal lock and condition variable. The condition variable functions(wait_until, notify, broadcast) can only be used inside a locked block. If your perl has been compiled without thread support the condition functions will not be available.

* lock_map $lvalue

Lock $lvalue until the end of the scope. If your perl does not support threads, this will be a no-op.

* wait_until { block } $lvalue

Wait for block to become true. After every failed attempt, wait for a signal. It returns the value returned by the block.

* notify $lvalue

This will signal to one listener that the map is available.

* broadcast $lvalue

This will signal to all listeners that the map is available.



These constants are used for sys_map. If you think you need them your mmap manpage will explain them, but in most cases you can skip sys_map altogether.


All previously mentioned functions are available for exportation, but none are exported by default. Some functions may not be available on your OS or your version of perl as specified above. A number of tags are defined to make importation easier.





This module depends on perl 5.8, Sub::Exporter::Progressive and PerlIO::Layers. Perl 5.8.8 or higher is recommended because older versions can give spurious warnings.

In perl versions before 5.11.5 many string functions including substr are limited to 32bit logic, even on 64bit architectures. Effectively this means you can't use them on strings bigger than 2GB. If you are working with such large files, it is strongly recommended to upgrade to 5.12.

In perl versions before 5.17.5, there is an off-by-one bug in Perl's regexp engine, as explained here. If the length of the file is an exact multiple of the page size, some regexps can trigger a segmentation fault.



As any piece of software, bugs are likely to exist here. Bug reports are welcome.

Please report any bugs or feature requests to bug-file-map at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Unicode file mappings are known to be buggy on perl 5.8.7 and lower.



Leon Timmermans <>


This software is copyright (c) 2008 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: