Mmap perl module, version alpha2 Copyright (c) 1996, Malcolm Beattie Copyright (c) 2002, Scott Walters This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with this kit. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this kit, in the file named "Artistic". If not, you can get one from the Perl distribution. You should also have received a copy of the GNU General Public License, in the file named "Copying". If not, you can get one from the Perl distribution or else write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. DESCRIPTION The Mmap module lets you use mmap to map in a file as a perl variable rather than reading the file into dynamically allocated memory. Multiple programs may map the same file into memory, and immediately see changes by each other. Memory may be allocated not attached to a file, and shared with subprocesses. It depends on your operating system supporting UNIX or POSIX.1b mmap, of course. You may use the new OO interface, or the old map() and unmap() interface. If you use the old interface, you need to be careful. 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 PROT_WRITE 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 substr as an lvalue and ensuring that the part of the string that you replace is exactly the same length. The new interface does not suffer from these problems. INSTALLATION Prerequisites are perl 5.002 and an operating system that has an implementation of mmap(2) with either the traditional or the POSIX.1b API. Perl 5.7.2 was tested with this release. Type perl Makefile.PL to write a personalised Makefile for your system. If your platform supports dynamic loading then just type make make test and provided you see "All tests successful" you can install it with make install If you need/want instead to make a statically linked perl which contains the module, then type make perl make test Documentation is included in pod format in Mmap.pm itself. The "make install" step will install an Mmap(3) man page or else you can use perldoc Mmap which will find the documentation whether it has been installed or if you run it from the Mmap distribution directory. BUGS You must explicitly use munmap() rather than letting perl itself clean up after you since perl 5.002 can't cope with variables whose string contents live in non-malloc'd memory. Malcolm Beattie 21 Jun 1996 Documentation updated to include information on OO interface 6/2002 Scott Walters