Documentation for the mmap module: proofreaders welcomed

This commit is contained in:
Andrew M. Kuchling 2000-06-17 22:39:05 +00:00
parent bea47e768d
commit b8050697b8
1 changed files with 120 additions and 0 deletions

120
Doc/lib/libmmap.tex Normal file
View File

@ -0,0 +1,120 @@
\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 have
a Python file object, its
\method{fileno()} method returns the file's handle, which is just an integer.
\var{tagname}, if specified, is a string giving a tag name for the mapping. XXX what is the purpose of the tag name?
\end{funcdesc}
\begin{funcdesc}{mmap}{file, 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 have a
Python file object, its \method{fileno()} method returns the file's
handle, which is just an integer.
\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 taken 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 the character at the current file position, and advancing
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 \var{byte} into memory at the current position of
the file pointer; the file position is advanced by 1.
\end{methoddesc}