mirror of https://github.com/python/cpython.git
133 lines
5.4 KiB
TeX
133 lines
5.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 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 \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).
|
|
|
|
\begin{funcdesc}{mmap}{fileno, length\optional{, tagname}}
|
|
\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 \code{0}, the maximum length of the map will be the
|
|
current size of the file when \function{mmap()} is called.
|
|
|
|
\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{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot}}}
|
|
\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}.
|
|
\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}{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}.
|
|
\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}{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.
|
|
\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}.
|
|
\end{methoddesc}
|