Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`mmap` --- Memory-mapped file support |
| 3 | ========================================== |
| 4 | |
| 5 | .. module:: mmap |
| 6 | :synopsis: Interface to memory-mapped files for Unix and Windows. |
| 7 | |
| 8 | |
| 9 | Memory-mapped file objects behave like both strings and like file objects. |
| 10 | Unlike normal string objects, however, these are mutable. You can use mmap |
| 11 | objects in most places where strings are expected; for example, you can use the |
| 12 | :mod:`re` module to search through a memory-mapped file. Since they're mutable, |
| 13 | you can change a single character by doing ``obj[index] = 'a'``, or change a |
| 14 | substring by assigning to a slice: ``obj[i1:i2] = '...'``. You can also read |
| 15 | and write data starting at the current file position, and :meth:`seek` through |
| 16 | the file to different positions. |
| 17 | |
| 18 | A memory-mapped file is created by the :func:`mmap` function, which is different |
| 19 | on Unix and on Windows. In either case you must provide a file descriptor for a |
| 20 | file opened for update. If you wish to map an existing Python file object, use |
| 21 | its :meth:`fileno` method to obtain the correct value for the *fileno* |
| 22 | parameter. Otherwise, you can open the file using the :func:`os.open` function, |
| 23 | which returns a file descriptor directly (the file still needs to be closed when |
| 24 | done). |
| 25 | |
| 26 | For both the Unix and Windows versions of the function, *access* may be |
| 27 | specified as an optional keyword parameter. *access* accepts one of three |
| 28 | values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to |
| 29 | specify readonly, write-through or copy-on-write memory respectively. *access* |
| 30 | can be used on both Unix and Windows. If *access* is not specified, Windows |
| 31 | mmap returns a write-through mapping. The initial memory values for all three |
| 32 | access types are taken from the specified file. Assignment to an |
| 33 | :const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception. Assignment |
| 34 | to an :const:`ACCESS_WRITE` memory map affects both memory and the underlying |
| 35 | file. Assignment to an :const:`ACCESS_COPY` memory map affects memory but does |
| 36 | not update the underlying file. |
| 37 | |
| 38 | .. versionchanged:: 2.5 |
| 39 | To map anonymous memory, -1 should be passed as the fileno along with the |
| 40 | length. |
| 41 | |
| 42 | |
| 43 | .. function:: mmap(fileno, length[, tagname[, access]]) |
| 44 | |
| 45 | **(Windows version)** Maps *length* bytes from the file specified by the file |
| 46 | handle *fileno*, and returns a mmap object. If *length* is larger than the |
| 47 | current size of the file, the file is extended to contain *length* bytes. If |
| 48 | *length* is ``0``, the maximum length of the map is the current size of the |
| 49 | file, except that if the file is empty Windows raises an exception (you cannot |
| 50 | create an empty mapping on Windows). |
| 51 | |
| 52 | *tagname*, if specified and not ``None``, is a string giving a tag name for the |
| 53 | mapping. Windows allows you to have many different mappings against the same |
| 54 | file. If you specify the name of an existing tag, that tag is opened, otherwise |
| 55 | a new tag of this name is created. If this parameter is omitted or ``None``, |
| 56 | the mapping is created without a name. Avoiding the use of the tag parameter |
| 57 | will assist in keeping your code portable between Unix and Windows. |
| 58 | |
| 59 | |
| 60 | .. function:: mmap(fileno, length[, flags[, prot[, access]]]) |
| 61 | :noindex: |
| 62 | |
| 63 | **(Unix version)** Maps *length* bytes from the file specified by the file |
| 64 | descriptor *fileno*, and returns a mmap object. If *length* is ``0``, the |
| 65 | maximum length of the map will be the current size of the file when :func:`mmap` |
| 66 | is called. |
| 67 | |
| 68 | *flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a |
| 69 | private copy-on-write mapping, so changes to the contents of the mmap object |
| 70 | will be private to this process, and :const:`MAP_SHARED` creates a mapping |
| 71 | that's shared with all other processes mapping the same areas of the file. The |
| 72 | default value is :const:`MAP_SHARED`. |
| 73 | |
| 74 | *prot*, if specified, gives the desired memory protection; the two most useful |
| 75 | values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify that the pages |
| 76 | may be read or written. *prot* defaults to :const:`PROT_READ \| PROT_WRITE`. |
| 77 | |
| 78 | *access* may be specified in lieu of *flags* and *prot* as an optional keyword |
| 79 | parameter. It is an error to specify both *flags*, *prot* and *access*. See |
| 80 | the description of *access* above for information on how to use this parameter. |
| 81 | |
| 82 | Memory-mapped file objects support the following methods: |
| 83 | |
| 84 | |
| 85 | .. method:: mmap.close() |
| 86 | |
| 87 | Close the file. Subsequent calls to other methods of the object will result in |
| 88 | an exception being raised. |
| 89 | |
| 90 | |
| 91 | .. method:: mmap.find(string[, start]) |
| 92 | |
| 93 | Returns the lowest index in the object where the substring *string* is found. |
| 94 | Returns ``-1`` on failure. *start* is the index at which the search begins, and |
| 95 | defaults to zero. |
| 96 | |
| 97 | |
| 98 | .. method:: mmap.flush([offset, size]) |
| 99 | |
| 100 | Flushes changes made to the in-memory copy of a file back to disk. Without use |
| 101 | of this call there is no guarantee that changes are written back before the |
| 102 | object is destroyed. If *offset* and *size* are specified, only changes to the |
| 103 | given range of bytes will be flushed to disk; otherwise, the whole extent of the |
| 104 | mapping is flushed. |
| 105 | |
| 106 | |
| 107 | .. method:: mmap.move(dest, src, count) |
| 108 | |
| 109 | Copy the *count* bytes starting at offset *src* to the destination index *dest*. |
| 110 | If the mmap was created with :const:`ACCESS_READ`, then calls to move will throw |
| 111 | a :exc:`TypeError` exception. |
| 112 | |
| 113 | |
| 114 | .. method:: mmap.read(num) |
| 115 | |
| 116 | Return a string containing up to *num* bytes starting from the current file |
| 117 | position; the file position is updated to point after the bytes that were |
| 118 | returned. |
| 119 | |
| 120 | |
| 121 | .. method:: mmap.read_byte() |
| 122 | |
| 123 | Returns a string of length 1 containing the character at the current file |
| 124 | position, and advances the file position by 1. |
| 125 | |
| 126 | |
| 127 | .. method:: mmap.readline() |
| 128 | |
| 129 | Returns a single line, starting at the current file position and up to the next |
| 130 | newline. |
| 131 | |
| 132 | |
| 133 | .. method:: mmap.resize(newsize) |
| 134 | |
| 135 | Resizes the map and the underlying file, if any. If the mmap was created with |
| 136 | :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will throw a |
| 137 | :exc:`TypeError` exception. |
| 138 | |
| 139 | |
| 140 | .. method:: mmap.seek(pos[, whence]) |
| 141 | |
| 142 | Set the file's current position. *whence* argument is optional and defaults to |
| 143 | ``os.SEEK_SET`` or ``0`` (absolute file positioning); other values are |
| 144 | ``os.SEEK_CUR`` or ``1`` (seek relative to the current position) and |
| 145 | ``os.SEEK_END`` or ``2`` (seek relative to the file's end). |
| 146 | |
| 147 | |
| 148 | .. method:: mmap.size() |
| 149 | |
| 150 | Return the length of the file, which can be larger than the size of the |
| 151 | memory-mapped area. |
| 152 | |
| 153 | |
| 154 | .. method:: mmap.tell() |
| 155 | |
| 156 | Returns the current position of the file pointer. |
| 157 | |
| 158 | |
| 159 | .. method:: mmap.write(string) |
| 160 | |
| 161 | Write the bytes in *string* into memory at the current position of the file |
| 162 | pointer; the file position is updated to point after the bytes that were |
| 163 | written. If the mmap was created with :const:`ACCESS_READ`, then writing to it |
| 164 | will throw a :exc:`TypeError` exception. |
| 165 | |
| 166 | |
| 167 | .. method:: mmap.write_byte(byte) |
| 168 | |
| 169 | Write the single-character string *byte* into memory at the current position of |
| 170 | the file pointer; the file position is advanced by ``1``. If the mmap was |
| 171 | created with :const:`ACCESS_READ`, then writing to it will throw a |
| 172 | :exc:`TypeError` exception. |
| 173 | |