Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Map(3)	      User Contributed Perl Documentation	  File::Map(3)

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

VERSION
       version 0.67

SYNOPSIS
	use File::Map 'map_file';

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

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

   Advantages of memory	mapping
       o   Unlike normal perl variables, mapped	memory is (usually) shared
	   between threads or forked processes.

       o   It is an efficient way to slurp an entire file. Unlike for example
	   File::Slurp,	this module returns almost immediately,	loading	the
	   pages lazily	on access. This	means you only 'pay' for the parts of
	   the file you	actually use.

       o   Perl	usually	doesn't	return memory to the system while running,
	   mapped memory can be	returned.

   Advantages of this module over other	similar	modules
       o   Safety and Speed

	   This	module is safe yet fast. Alternatives are either fast but can
	   cause segfaults or lose the mapping when not	used correctly,	or are
	   safe	but rather slow. File::Map is as fast as a normal string yet
	   safe.

       o   Simplicity

	   It offers a simple interface	targeted at common usage patterns

	   o   Files are mapped	into a variable	that can be read just like any
	       other variable, and it can be written to	using standard Perl
	       techniques such as regexps and "substr".

	   o   Files can be mapped using a set of simple functions. There is
	       no need to know weird constants or the order of 6 arguments.

	   o   It will automatically unmap the file when the scalar gets
	       destroyed. This works correctly even in multi-threaded
	       programs.

       o   Portability

	   File::Map supports Unix and Windows.

       o   Thread synchronization

	   It has built-in support for thread synchronization.

FUNCTIONS
   Mapping
       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.

   Auxiliary
       * 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:.

       o normal

	 Specifies that	the application	has no advice to give on its behavior
	 with respect to the mapped variable. It is the	default	characteristic
	 if no advice is given.

       o random

	 Specifies that	the application	expects	to access the mapped variable
	 in a random order.

       o sequential

	 Specifies that	the application	expects	to access the mapped variable
	 sequentially from start to end.

       o willneed

	 Specifies that	the application	expects	to access the mapped variable
	 in the	near future.

       o dontneed

	 Specifies that	the application	expects	that it	will not access	the
	 mapped	variable in the	near future.

       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 "open", but also accepts sys_map style	constants.

   Locking
       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.

   Constants
       PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC, MAP_ANONYMOUS, MAP_SHARED,
       MAP_PRIVATE, MAP_ANON, MAP_FILE
	   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.

EXPORTS
       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.

       o   :map

	   map_handle, map_file, map_anonymous,	sys_map, unmap

       o   :extra

	   remap, sync,	pin, unpin, advise, protect

       o   :lock

	   lock_map, wait_until, notify, broadcast

       o   :constants

	   PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC,	MAP_ANONYMOUS,
	   MAP_SHARED, MAP_PRIVATE, MAP_ANON, MAP_FILE

       o   :all

	   All functions defined in this module.

DIAGNOSTICS
   Exceptions
       o   Could not <function name>: this variable is not memory mapped

	   An attempt was made to "sync", "remap", "unmap", "pin", "unpin",
	   "advise" or "lock_map" an unmapped variable.

       o   Could not <function name>: <system error>

	   Your	OS didn't allow	File::Map to do	what you asked it to do	for
	   some	reason.

       o   Trying to <function_name> on	an unlocked map

	   You tried to	"wait_until", "notify" or "broadcast" on an unlocked
	   variable.

       o   Zero	length not allowed for anonymous map

	   A zero length anonymous map is not possible (or in any way useful).

       o   Can't remap a shared	mapping

	   An attempt was made to remap	a mapping that is shared among
	   different threads, this is not possible.

       o   Window (<start>, <end>) is outside the file

	   The offset and/or length you	specified were invalid for this	file.

       o   Can't map fake filehandle

	   The filehandle you provided is not real. This may mean it's a
	   scalar string handle	or a tied handle.

       o   No such flag	<flag_name>

	   The flag given for map_anonymous isn't valid, it should either be
	   "shared" or "private".

   Warnings
       o   Writing directly to a memory	mapped file is not recommended

	   Due to the way perl works internally, it's not possible to write a
	   mapping implementation that allows direct assignment	yet performs
	   well. As a compromise, File::Map is capable of fixing up the	mess
	   if you do it	nonetheless, but it will warn you that you're doing
	   something you shouldn't. This warning is only given when "use
	   warnings 'substr'" is in effect.

       o   Truncating new value	to size	of the memory map

	   This	warning	is additional to the previous one, warning you that
	   you're losing data. This warning is only given when "use warnings
	   'substr'" is	in effect.

       o   Shouldn't mmap non-binary filehandle

	   You tried to	to map a filehandle that has some encoding layer.
	   Encoding layers are not supported by	File::Map. This	warning	is
	   only	given when "use	warnings 'layer'" is in	effect.	Note that this
	   may become an exception in a	future version.

       o   Unknown advice '<advice>'

	   You gave advise an advice it	didn't know. This is either a typo or
	   a portability issue.	This warning is	only given when	"use warnings
	   'portable'" is in effect.

       o   Syncing a readonly map makes	no sense

	   "sync" flushes changes to the map to	the filesystem.	This obviously
	   is of little	use when you can't change the map. This	warning	is
	   only	given when "use	warnings 'io'" is in effect.

       o   Can't overwrite an empty map

	   Overwriting an empty	map is rather nonsensical, hence a warning is
	   given when this is tried. This warning is only given	when "use
	   warnings 'substr'" is in effect.

DEPENDENCIES
       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
       <http://rt.perl.org/rt3//Public/Bug/Display.html?id=72784>, 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
       <http://rt.perl.org/rt3//Public/Bug/Display.html?id=73542>. If the
       length of the file is an	exact multiple of the page size, some regexps
       can trigger a segmentation fault.

PITFALLS
       o   This	module doesn't do any encoding or newline transformation for
	   you,	and will reject	any filehandle with such features enabled as
	   mapping it would return a different value than reading it normally.
	   Most	importantly this means that on Windows you have	to remember to
	   use the ":raw" open mode or binmode to make your filehandles	binary
	   before mapping them,	as by default it would do "crlf"
	   transformation. See PerlIO for more information on how that works.

       o   You can map a ":utf8" filehandle, but writing to it may be tricky.
	   Hic sunt dracones.

       o   You probably	don't want to use ">" as a mode. This does not give
	   you reading permissions on many architectures, resulting in
	   segmentation	faults when trying to read a variable (confusingly, it
	   will	work on	some others like x86).

BUGS AND LIMITATIONS
       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
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Map>.  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.

SEE ALSO
       o   Sys::Mmap, the original Perl	mmap module

       o   mmap(2), your mmap man page

       o   Win32::MMF

       o   CreateFileMapping at	MSDN:
	   <http://msdn.microsoft.com/en-us/library/aa366537(VS.85).aspx>

AUTHOR
       Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE
       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.

perl v5.32.1			  2021-02-28			  File::Map(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | FUNCTIONS | EXPORTS | DIAGNOSTICS | DEPENDENCIES | PITFALLS | BUGS AND LIMITATIONS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Map&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help