diff options
| -rw-r--r-- | Doc/lib/libmmap.tex | 54 |
1 files changed, 24 insertions, 30 deletions
diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex index 466dfcc..426f658 100644 --- a/Doc/lib/libmmap.tex +++ b/Doc/lib/libmmap.tex @@ -4,8 +4,9 @@ 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 +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 @@ -23,6 +24,21 @@ If you wish to map an existing Python file object, use its \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. Assigment to an +\constant{ACCESS_COPY} memory map affects memory but does not update +the underlying file. + \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 @@ -38,23 +54,10 @@ directly (the file still needs to be closed when done). mapping is created without a name. Avoiding the use of the tag parameter will assist in keeping your code portable between \UNIX{} and Windows. - - \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. Assigment to an - \constant{ACCESS_COPY} memory map affects memory but does not update - the underlying file. \end{funcdesc} -\begin{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot\optional{, access}}}} +\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. @@ -72,19 +75,10 @@ directly (the file still needs to be closed when done). 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. \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. It is an error to specify both \var{flags}, - \var{prot} and \var{access}. 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. Assigment to an - \constant{ACCESS_COPY} memory map affects memory but does not update - the underlying file. -\end{funcdesc} + 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: |