Memory-mapped file objects behave like both strings and like file objects. Unlike normal
string objects, however, these are mutable. You can use mmap objects in most places where
strings are expected; for example, you can use the re module to search
through a memory-mapped file. Since they're mutable, you can change a single character by
obj[index] = 'a', or change a substring by assigning to a slice:
obj[i1:i2] = '...'. You can also read and write data
starting at the current file position, and seek() through the file to
A memory-mapped file is created by the mmap() function, which is
different on Unix and on Windows. In either
case you must provide a file descriptor for a file opened for update. If you wish to map an
existing Python file object, use its fileno() method to obtain the
correct value for the fileno parameter. Otherwise, you can open the file using the os.open() function, which returns a file descriptor directly (the file
still needs to be closed when done).
For both the Unix and Windows versions of
the function, access may be specified as an optional keyword parameter. access
accepts one of three values: ACCESS_READ, ACCESS_WRITE,
or ACCESS_COPY to specify readonly, write-through or copy-on-write
memory respectively. access can be used on both Unix and Windows. If access is not
specified, Windows mmap returns a write-through mapping. The initial memory values for all
three access types are taken from the specified file. Assignment to an ACCESS_READ
memory map raises a TypeError exception. Assignment to an ACCESS_WRITE memory map affects both memory and the underlying file.
Assigment to an ACCESS_COPY memory map affects memory but does not
update the underlying file.
||fileno, length[, tagname[, access]])
- (Windows version) Maps length bytes from the file specified by the
file handle fileno, and returns a mmap object. If length is
the maximum length of the map will be the current size of the file when mmap() is called.
tagname, if specified and not
None, is a string giving a tag
name for the mapping. Windows allows you to have many different mappings against the same
file. If you specify the name of an existing tag, that tag is opened, otherwise a new tag
of this name is created. If this parameter is omitted or
None, the mapping is
created without a name. Avoiding the use of the tag parameter will assist in keeping your
code portable between Unix and Windows.
||fileno, length[, flags[, prot[,
- (Unix version) Maps length
bytes from the file specified by the file descriptor fileno, and returns a mmap
flags specifies the nature of the mapping. MAP_PRIVATE
creates a private copy-on-write mapping, so changes to the contents of the mmap object
will be private to this process, and MAP_SHARED creates a
mapping that's shared with all other processes mapping the same areas of the file. The
default value is MAP_SHARED.
prot, if specified, gives the desired memory protection; the two most useful
values are PROT_READ and PROT_WRITE,
to specify that the pages may be read or written. prot defaults to PROT_READ | PROT_WRITE.
access may be specified in lieu of flags and prot as
an optional keyword parameter. It is an error to specify both flags, prot
and access. See the description of access above for information on
how to use this parameter.
Memory-mapped file objects support the following methods:
- Close the file. Subsequent calls to other methods of the object will result in an
exception being raised.
- Returns the lowest index in the object where the substring string is found.
-1 on failure. start is the index at which the search
begins, and defaults to zero.
- Flushes changes made to the in-memory copy of a file back to disk. Without use of this
call there is no guarantee that changes are written back before the object is destroyed.
If offset and size are specified, only changes to the given range of
bytes will be flushed to disk; otherwise, the whole extent of the mapping is flushed.
- Copy the count bytes starting at offset src to the destination
index dest. If the mmap was created with ACCESS_READ,
then calls to move will throw a TypeError exception.
- Return a string containing up to num bytes starting from the current file
position; the file position is updated to point after the bytes that were returned.
- Returns a string of length 1 containing the character at the current file position, and
advances the file position by 1.
- Returns a single line, starting at the current file position and up to the next newline.
- If the mmap was created with ACCESS_READ or ACCESS_COPY, resizing the map will throw a TypeError
- Set the file's current position. whence argument is optional and defaults to
(absolute file positioning); other values are
1 (seek relative to the current
2 (seek relative to the file's end).
- Return the length of the file, which can be larger than the size of the memory-mapped
- Returns the current position of the file pointer.
- Write the bytes in string into memory at the current position of the file
pointer; the file position is updated to point after the bytes that were written. If the
mmap was created with ACCESS_READ, then writing to it will throw
a TypeError exception.
- Write the single-character string byte into memory at the current position of
the file pointer; the file position is advanced by
1.If the mmap was created
with ACCESS_READ, then writing to it will throw a TypeError exception.