diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libmmap.tex | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-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.tex | 171 |
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} |