summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libmmap.tex
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2007-08-15 14:27:07 (GMT)
committerGeorg Brandl <georg@python.org>2007-08-15 14:27:07 (GMT)
commit739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch)
treef82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libmmap.tex
parent2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff)
downloadcpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.zip
cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz
cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.bz2
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib/libmmap.tex')
-rw-r--r--Doc/lib/libmmap.tex171
1 files changed, 0 insertions, 171 deletions
diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex
deleted file mode 100644
index 345aeea..0000000
--- a/Doc/lib/libmmap.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-\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. Assignment to an
-\constant{ACCESS_COPY} memory map affects memory but does not update
-the underlying file. \versionchanged[To map anonymous memory,
--1 should be passed as the fileno along with the length]{2.5}
-
-\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. 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{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}[mmap]{close}{}
- Close the file. Subsequent calls to other methods of the object
- will result in an exception being raised.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{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}[mmap]{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}[mmap]{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}[mmap]{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}[mmap]{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}[mmap]{readline}{}
- Returns a single line, starting at the current file position and up to
- the next newline.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{resize}{\var{newsize}}
- Resizes the map and the underlying file, if any.
- 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}[mmap]{seek}{pos\optional{, whence}}
- Set the file's current position. \var{whence} argument is optional
- and defaults to \code{os.SEEK_SET} or \code{0} (absolute file
- positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek
- relative to the current position) and \code{os.SEEK_END} or \code{2}
- (seek relative to the file's end).
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{size}{}
- Return the length of the file, which can be larger than the size of
- the memory-mapped area.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{tell}{}
- Returns the current position of the file pointer.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{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}[mmap]{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}