mirror of https://github.com/python/cpython
130 lines
5.1 KiB
TeX
130 lines
5.1 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 mutable strings and like
|
|
file objects. 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 following function, which is
|
|
different on Unix and on Windows.
|
|
|
|
\begin{funcdesc}{mmap}{fileno, length \optional{, tagname} }
|
|
(Windows version) Maps \var{length} bytes from the file specified by
|
|
the file handle \var{fileno}, and returns a mmap object. 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.
|
|
|
|
\var{tagname}, if specified, 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
|
|
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{funcdesc}{mmap}{fileno, size \optional{, flags, prot}}
|
|
(Unix version) Maps \var{length} bytes from the file specified by the
|
|
file handle \var{fileno}, and returns a mmap object. 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.
|
|
|
|
\var{flags} specifies the nature of the mapping.
|
|
\code{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 \code{MAP_SHARED} creates a mapping that's shared
|
|
with all other processes mapping the same areas of the file.
|
|
The default value is \code{MAP_SHARED}.
|
|
|
|
\var{prot}, if specified, gives the desired memory protection; the two
|
|
most useful values are \code{PROT_READ} and \code{PROT_WRITE}, to
|
|
specify that the pages may be read or written.
|
|
\var{prot} defaults to \code{PROT_READ | PROT_WRITE}.
|
|
\end{funcdesc}
|
|
|
|
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}{\var{string} \optional{, \var{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{\var{offset}, \var{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}.
|
|
\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}}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{seek}{\var{pos} \optional{, \var{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.
|
|
\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 1.
|
|
\end{methoddesc}
|
|
|
|
|