diff options
Diffstat (limited to 'Doc/lib/libmmap.tex')
| -rw-r--r-- | Doc/lib/libmmap.tex | 162 |
1 files changed, 100 insertions, 62 deletions
diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex index 0bd0332..917635b 100644 --- a/Doc/lib/libmmap.tex +++ b/Doc/lib/libmmap.tex @@ -1,5 +1,5 @@ \section{\module{mmap} --- - Memory-mapped file support} +Memory-mapped file support} \declaremodule{builtin}{mmap} \modulesynopsis{Interface to memory-mapped files for Unix and Windows.} @@ -23,36 +23,67 @@ 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). -\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. +\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 \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. + + \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}}} -\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}. +\begin{funcdesc}{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. + + \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. \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} @@ -60,73 +91,80 @@ 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. + 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. + 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. + 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}. + 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}{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. + 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. + 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. + Returns a single line, starting at the current file position and up to + the next newline. \end{methoddesc} \begin{methoddesc}{resize}{\var{newsize}} + 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}{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). + 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. + 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. + 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. + 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}{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}. + 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} |