GNU Info

(python2.1-lib.info)mmap

---

Next: anydbm Prev: Queue Up: Optional Operating System Services

---

Enter node , (file) or (file)node

Memory-mapped file support
==========================

Interface to memory-mapped files for Unix and Windows.

Memory-mapped file objects behave like both mutable strings and like
file objects.  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 doing `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 different positions.

A memory-mapped file is created by the following function, which is
different on Unix and on Windows.

`mmap(fileno, length[, tagname])'
     *(Windows version)*  Maps LENGTH bytes from the file specified by
     the file handle FILENO, and returns a mmap object.  If LENGTH is
     `0', the maximum length of the map will be the current size of the
     file when `mmap()' is called.  If you wish to map an existing
     Python file object, use its `fileno()' method to obtain the
     correct value for the FILENO parameter.  The file must be opened
     for update.

     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.

`mmap(fileno, size[, flags, prot])'
     *(UNIX version)*  Maps LENGTH bytes from the file specified by the
     file handle FILENO, and returns a mmap object.  If you wish to map
     an existing Python file object, use its `fileno()' method to
     obtain the correct value for the FILENO parameter.  The file must
     be opened for update.

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

Memory-mapped file objects support the following methods:

`close()'
     Close the file.  Subsequent calls to other methods of the object
     will result in an exception being raised.

`find(string[, start])'
     Returns the lowest index in the object where the substring STRING
     is found.  Returns `-1' on failure.  START is the index at which
     the search begins, and defaults to zero.

`flush([offset, size])'
     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.

`move(DEST, SRC, COUNT)'
     Copy the COUNT bytes starting at offset SRC to the destination
     index DEST.

`read(NUM)'
     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.

`read_byte()'
     Returns a string of length 1 containing the character at the
     current file position, and advances the file position by 1.

`readline()'
     Returns a single line, starting at the current file position and
     up to the next newline.

`resize(NEWSIZE)'

`seek(pos[, whence])'
     Set the file's current position.  WHENCE argument is optional and
     defaults to `0' (absolute file positioning); other values are `1'
     (seek relative to the current position) and `2' (seek relative to
     the file's end).

`size()'
     Return the length of the file, which can be larger than the size
     of the memory-mapped area.

`tell()'
     Returns the current position of the file pointer.

`write(STRING)'
     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.

`write_byte(BYTE)'
     Write the single-character string BYTE into memory at the current
     position of the file pointer; the file position is advanced by `1'.