Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 1 | \section{\module{mmap} --- |
| 2 | Memory-mapped file support} |
| 3 | |
| 4 | \declaremodule{builtin}{mmap} |
| 5 | \modulesynopsis{Interface to memory-mapped files for Unix and Windows.} |
| 6 | |
| 7 | Memory-mapped file objects behave like both mutable strings and like |
| 8 | file objects. You can use mmap objects in most places where strings |
| 9 | are expected; for example, you can use the \module{re} module to |
| 10 | search through a memory-mapped file. Since they're mutable, you can |
| 11 | change a single character by doing \code{obj[ \var{index} ] = 'a'}, or |
| 12 | change a substring by assigning to a slice: |
| 13 | \code{obj[ \var{i1}:\var{i2} ] = '...'}. You can also read and write |
| 14 | data starting at the current file position, and \method{seek()} |
| 15 | through the file to different positions. |
| 16 | |
| 17 | A memory-mapped file is created by the following function, which is |
| 18 | different on Unix and on Windows. |
| 19 | |
| 20 | \begin{funcdesc}{mmap}{fileno, length \optional{, tagname} } |
| 21 | (Windows version) Maps \var{length} bytes from the file specified by |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 22 | the file handle \var{fileno}, and returns a mmap object. If you wish |
| 23 | to map an existing Python file object, use its \method{fileno()} |
| 24 | method to obtain the correct value for the \var{fileno} parameter. |
| 25 | |
| 26 | \var{tagname}, if specified, is a string giving a tag name for the mapping. |
| 27 | Windows allows you to have many different mappings against the same |
| 28 | file. If you specify the name of an existing tag, that tag is opened, |
| 29 | otherwise a new tag of this name is created. If this parameter is |
| 30 | None, the mapping is created without a name. Avoiding the use of the |
| 31 | tag parameter will assist in keeping your code portable between Unix |
| 32 | and Windows. |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 33 | \end{funcdesc} |
| 34 | |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 35 | \begin{funcdesc}{mmap}{fileno, size \optional{, flags, prot}} |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 36 | (Unix version) Maps \var{length} bytes from the file specified by the |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 37 | file handle \var{fileno}, and returns a mmap object. If you wish to |
| 38 | map an existing Python file object, use its \method{fileno()} method |
| 39 | to obtain the correct value for the \var{fileno} parameter. |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 40 | |
| 41 | \var{flags} specifies the nature of the mapping. |
| 42 | \code{MAP_PRIVATE} creates a private copy-on-write mapping, so |
| 43 | changes to the contents of the mmap object will be private to this |
| 44 | process, and \code{MAP_SHARED} creates a mapping that's shared |
| 45 | with all other processes mapping the same areas of the file. |
| 46 | The default value is \code{MAP_SHARED}. |
| 47 | |
| 48 | \var{prot}, if specified, gives the desired memory protection; the two |
| 49 | most useful values are \code{PROT_READ} and \code{PROT_WRITE}, to |
| 50 | specify that the pages may be read or written. |
| 51 | \var{prot} defaults to \code{PROT_READ | PROT_WRITE}. |
| 52 | \end{funcdesc} |
| 53 | |
| 54 | Memory-mapped file objects support the following methods: |
| 55 | |
| 56 | |
| 57 | \begin{methoddesc}{close}{} |
| 58 | Close the file. Subsequent calls to other methods of the object |
| 59 | will result in an exception being raised. |
| 60 | \end{methoddesc} |
| 61 | |
| 62 | \begin{methoddesc}{find}{\var{string} \optional{, \var{start}}} |
| 63 | Returns the lowest index in the object where the substring \var{string} is |
| 64 | found. Returns \code{-1} on failure. |
| 65 | \var{start} is the index at which the search begins, and defaults to zero. |
| 66 | \end{methoddesc} |
| 67 | |
| 68 | \begin{methoddesc}{flush}{\optional{\var{offset}, \var{size}}} |
| 69 | Flushes changes made to the in-memory copy of a file back to disk. |
| 70 | Without use of this call there is no guarantee that changes are |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 71 | written back before the object is destroyed. If \var{offset} and |
| 72 | \var{size} are specified, only changes to the given range of bytes |
| 73 | will be flushed to disk; otherwise, the whole extent of the mapping is |
| 74 | flushed. |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 75 | \end{methoddesc} |
| 76 | |
| 77 | \begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}} |
| 78 | Copy the \var{count} bytes starting at offset \var{src} |
| 79 | to the destination index \var{dest}. |
| 80 | \end{methoddesc} |
| 81 | |
| 82 | \begin{methoddesc}{read}{\var{num}} |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 83 | Return a string containing up to \var{num} bytes starting from the |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 84 | current file position; the file position is updated to point after the |
| 85 | bytes that were returned. |
| 86 | \end{methoddesc} |
| 87 | |
| 88 | \begin{methoddesc}{read_byte}{} |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 89 | Returns a string of length 1 containing the character at the current |
| 90 | file position, and advances the file position by 1. |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 91 | \end{methoddesc} |
| 92 | |
| 93 | \begin{methoddesc}{readline}{} |
| 94 | Returns a single line, starting at the current file position and up to |
| 95 | the next newline. |
| 96 | \end{methoddesc} |
| 97 | |
| 98 | \begin{methoddesc}{resize}{\var{newsize}} |
| 99 | \end{methoddesc} |
| 100 | |
| 101 | \begin{methoddesc}{seek}{\var{pos} \optional{, \var{whence}}} |
| 102 | Set the file's current position. |
| 103 | \var{whence} argument is optional and defaults to \code{0} |
| 104 | (absolute file positioning); other values are \code{1} (seek |
| 105 | relative to the current position) and \code{2} (seek relative to the |
| 106 | file's end). |
| 107 | \end{methoddesc} |
| 108 | |
| 109 | \begin{methoddesc}{size}{} |
| 110 | Return the length of the file, which can be larger than the size |
| 111 | of the memory-mapped area. |
| 112 | \end{methoddesc} |
| 113 | |
| 114 | \begin{methoddesc}{tell}{} |
| 115 | Returns the current position of the file pointer. |
| 116 | \end{methoddesc} |
| 117 | |
| 118 | \begin{methoddesc}{write}{\var{string}} |
| 119 | Write the bytes in \var{string} into memory at the current position of |
| 120 | the file pointer; the file position is updated to point after the |
| 121 | bytes that were written. |
| 122 | \end{methoddesc} |
| 123 | |
| 124 | \begin{methoddesc}{write_byte}{\var{byte}} |
Andrew M. Kuchling | 0adfb45 | 2000-06-18 04:17:38 +0000 | [diff] [blame] | 125 | Write the single-character string \var{byte} into memory at the current position of |
Andrew M. Kuchling | b805069 | 2000-06-17 22:39:05 +0000 | [diff] [blame] | 126 | the file pointer; the file position is advanced by 1. |
| 127 | \end{methoddesc} |
| 128 | |
| 129 | |