mirror of https://github.com/python/cpython
167 lines
7.4 KiB
TeX
167 lines
7.4 KiB
TeX
\section{\module{mmap} ---
|
|
Memory-mapped file support}
|
|
|
|
\declaremodule{builtin}{mmap}
|
|
\modulesynopsis{Interface to memory-mapped files for \UNIX\ and Windows.}
|
|
|
|
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 \module{re} module to
|
|
search through a memory-mapped file. Since they're mutable, you can
|
|
change a single character by doing \code{obj[\var{index}] = 'a'}, or
|
|
change a substring by assigning to a slice:
|
|
\code{obj[\var{i1}:\var{i2}] = '...'}. You can also read and write
|
|
data starting at the current file position, and \method{seek()}
|
|
through the file to different positions.
|
|
|
|
A memory-mapped file is created by the \function{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
|
|
\method{fileno()} method to obtain the correct value for the
|
|
\var{fileno} parameter. Otherwise, you can open the file using the
|
|
\function{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,
|
|
\var{access} may be specified as an optional keyword parameter.
|
|
\var{access} accepts one of three values: \constant{ACCESS_READ},
|
|
\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
|
|
readonly, write-through or copy-on-write memory respectively.
|
|
\var{access} can be used on both \UNIX{} and Windows. If
|
|
\var{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
|
|
\constant{ACCESS_READ} memory map raises a \exception{TypeError}
|
|
exception. Assignment to an \constant{ACCESS_WRITE} memory map
|
|
affects both memory and the underlying file. Assigment to an
|
|
\constant{ACCESS_COPY} memory map affects memory but does not update
|
|
the underlying file.
|
|
|
|
\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
|
|
\strong{(Windows version)} Maps \var{length} bytes from the file
|
|
specified by the file handle \var{fileno}, and returns a mmap
|
|
object. If \var{length} is larger than the current size of the file,
|
|
the file is extended to contain \var{length} bytes. If \var{length}
|
|
is \code{0}, the maximum length of the map is the current size
|
|
of the file, except that if the file is empty Windows raises an
|
|
exception (you cannot create an empty mapping on Windows).
|
|
|
|
\var{tagname}, if specified and not \code{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 \code{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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
|
|
prot\optional{, access}}}}
|
|
\strong{(\UNIX{} version)} Maps \var{length} bytes from the file
|
|
specified by the file descriptor \var{fileno}, and returns a mmap
|
|
object.
|
|
|
|
\var{flags} specifies the nature of the mapping.
|
|
\constant{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 \constant{MAP_SHARED} creates a mapping that's shared
|
|
with all other processes mapping the same areas of the file. The
|
|
default value is \constant{MAP_SHARED}.
|
|
|
|
\var{prot}, if specified, gives the desired memory protection; the
|
|
two most useful values are \constant{PROT_READ} and
|
|
\constant{PROT_WRITE}, to specify that the pages may be read or
|
|
written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
|
|
|
|
\var{access} may be specified in lieu of \var{flags} and \var{prot}
|
|
as an optional keyword parameter. It is an error to specify both
|
|
\var{flags}, \var{prot} and \var{access}. See the description of
|
|
\var{access} above for information on how to use this parameter.
|
|
\end{funcdescni}
|
|
|
|
|
|
Memory-mapped file objects support the following methods:
|
|
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Close the file. Subsequent calls to other methods of the object
|
|
will result in an exception being raised.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{find}{string\optional{, start}}
|
|
Returns the lowest index in the object where the substring
|
|
\var{string} is found. Returns \code{-1} on failure. \var{start}
|
|
is the index at which the search begins, and defaults to zero.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{flush}{\optional{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 \var{offset} and
|
|
\var{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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}}
|
|
Copy the \var{count} bytes starting at offset \var{src} to the
|
|
destination index \var{dest}. If the mmap was created with
|
|
\constant{ACCESS_READ}, then calls to move will throw a
|
|
\exception{TypeError} exception.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read}{\var{num}}
|
|
Return a string containing up to \var{num} bytes starting from the
|
|
current file position; the file position is updated to point after the
|
|
bytes that were returned.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_byte}{}
|
|
Returns a string of length 1 containing the character at the current
|
|
file position, and advances the file position by 1.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{readline}{}
|
|
Returns a single line, starting at the current file position and up to
|
|
the next newline.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{resize}{\var{newsize}}
|
|
If the mmap was created with \constant{ACCESS_READ} or
|
|
\constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{seek}{pos\optional{, whence}}
|
|
Set the file's current position. \var{whence} argument is optional
|
|
and defaults to \code{0} (absolute file positioning); other values
|
|
are \code{1} (seek relative to the current position) and \code{2}
|
|
(seek relative to the file's end).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{size}{}
|
|
Return the length of the file, which can be larger than the size of
|
|
the memory-mapped area.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{tell}{}
|
|
Returns the current position of the file pointer.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{write}{\var{string}}
|
|
Write the bytes in \var{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
|
|
\constant{ACCESS_READ}, then writing to it will throw a
|
|
\exception{TypeError} exception.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{write_byte}{\var{byte}}
|
|
Write the single-character string \var{byte} into memory at the
|
|
current position of the file pointer; the file position is advanced
|
|
by \code{1}.If the mmap was created with \constant{ACCESS_READ},
|
|
then writing to it will throw a \exception{TypeError} exception.
|
|
\end{methoddesc}
|