Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`mmap` --- Memory-mapped file support |
| 2 | ========================================== |
| 3 | |
| 4 | .. module:: mmap |
| 5 | :synopsis: Interface to memory-mapped files for Unix and Windows. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 9 | Memory-mapped file objects behave like both :class:`bytearray` and like |
| 10 | :term:`file objects <file object>`. You can use mmap objects in most places |
| 11 | where :class:`bytearray` are expected; for example, you can use the :mod:`re` |
| 12 | module to search through a memory-mapped file. You can also change a single |
| 13 | byte by doing ``obj[index] = 97``, or change a subsequence by assigning to a |
| 14 | slice: ``obj[i1:i2] = b'...'``. You can also read and write data starting at |
| 15 | the current file position, and :meth:`seek` through the file to different positions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 17 | A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 18 | different on Unix and on Windows. In either case you must provide a file |
| 19 | descriptor for a file opened for update. If you wish to map an existing Python |
| 20 | file object, use its :meth:`fileno` method to obtain the correct value for the |
| 21 | *fileno* parameter. Otherwise, you can open the file using the |
| 22 | :func:`os.open` function, which returns a file descriptor directly (the file |
| 23 | still needs to be closed when done). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
Ross Lagerwall | 59c01ed | 2011-07-25 07:12:43 +0200 | [diff] [blame] | 25 | .. note:: |
| 26 | If you want to create a memory-mapping for a writable, buffered file, you |
| 27 | should :func:`~io.IOBase.flush` the file first. This is necessary to ensure |
| 28 | that local modifications to the buffers are actually available to the |
| 29 | mapping. |
| 30 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 31 | For both the Unix and Windows versions of the constructor, *access* may be |
Justus Schwabedal | 5a8a84b | 2017-11-07 15:51:43 -0500 | [diff] [blame] | 32 | specified as an optional keyword parameter. *access* accepts one of four |
| 33 | values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to |
| 34 | specify read-only, write-through or copy-on-write memory respectively, or |
| 35 | :const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix |
| 36 | and Windows. If *access* is not specified, Windows mmap returns a |
| 37 | write-through mapping. The initial memory values for all three access types |
| 38 | are taken from the specified file. Assignment to an :const:`ACCESS_READ` |
| 39 | memory map raises a :exc:`TypeError` exception. Assignment to an |
| 40 | :const:`ACCESS_WRITE` memory map affects both memory and the underlying file. |
| 41 | Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not |
| 42 | update the underlying file. |
| 43 | |
| 44 | .. versionchanged:: 3.7 |
| 45 | Added :const:`ACCESS_DEFAULT` constant. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 47 | To map anonymous memory, -1 should be passed as the fileno along with the length. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 49 | .. class:: mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 51 | **(Windows version)** Maps *length* bytes from the file specified by the |
| 52 | file handle *fileno*, and creates a mmap object. If *length* is larger |
| 53 | than the current size of the file, the file is extended to contain *length* |
| 54 | bytes. If *length* is ``0``, the maximum length of the map is the current |
| 55 | size of the file, except that if the file is empty Windows raises an |
| 56 | exception (you cannot create an empty mapping on Windows). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 58 | *tagname*, if specified and not ``None``, is a string giving a tag name for |
| 59 | the mapping. Windows allows you to have many different mappings against |
| 60 | the same file. If you specify the name of an existing tag, that tag is |
| 61 | opened, otherwise a new tag of this name is created. If this parameter is |
| 62 | omitted or ``None``, the mapping is created without a name. Avoiding the |
| 63 | use of the tag parameter will assist in keeping your code portable between |
| 64 | Unix and Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 66 | *offset* may be specified as a non-negative integer offset. mmap references |
| 67 | will be relative to the offset from the beginning of the file. *offset* |
| 68 | defaults to 0. *offset* must be a multiple of the ALLOCATIONGRANULARITY. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 70 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 71 | .. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | :noindex: |
| 73 | |
| 74 | **(Unix version)** Maps *length* bytes from the file specified by the file |
| 75 | descriptor *fileno*, and returns a mmap object. If *length* is ``0``, the |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 76 | maximum length of the map will be the current size of the file when |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 77 | :class:`~mmap.mmap` is called. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | *flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 80 | private copy-on-write mapping, so changes to the contents of the mmap |
| 81 | object will be private to this process, and :const:`MAP_SHARED` creates a |
| 82 | mapping that's shared with all other processes mapping the same areas of |
| 83 | the file. The default value is :const:`MAP_SHARED`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 85 | *prot*, if specified, gives the desired memory protection; the two most |
| 86 | useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify |
| 87 | that the pages may be read or written. *prot* defaults to |
| 88 | :const:`PROT_READ \| PROT_WRITE`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 90 | *access* may be specified in lieu of *flags* and *prot* as an optional |
| 91 | keyword parameter. It is an error to specify both *flags*, *prot* and |
| 92 | *access*. See the description of *access* above for information on how to |
| 93 | use this parameter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 95 | *offset* may be specified as a non-negative integer offset. mmap references |
| 96 | will be relative to the offset from the beginning of the file. *offset* |
| 97 | defaults to 0. *offset* must be a multiple of the PAGESIZE or |
| 98 | ALLOCATIONGRANULARITY. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 99 | |
Victor Stinner | a6cd0cf | 2011-05-02 01:05:37 +0200 | [diff] [blame] | 100 | To ensure validity of the created memory mapping the file specified |
| 101 | by the descriptor *fileno* is internally automatically synchronized |
| 102 | with physical backing store on Mac OS X and OpenVMS. |
| 103 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 104 | This example shows a simple way of using :class:`~mmap.mmap`:: |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 105 | |
| 106 | import mmap |
| 107 | |
| 108 | # write a simple example file |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 109 | with open("hello.txt", "wb") as f: |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 110 | f.write(b"Hello Python!\n") |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 111 | |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 112 | with open("hello.txt", "r+b") as f: |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 113 | # memory-map the file, size 0 means whole file |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 114 | mm = mmap.mmap(f.fileno(), 0) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 115 | # read content via standard file methods |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 116 | print(mm.readline()) # prints b"Hello Python!\n" |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 117 | # read content via slice notation |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 118 | print(mm[:5]) # prints b"Hello" |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 119 | # update content using slice notation; |
| 120 | # note that new content must have same size |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 121 | mm[6:] = b" world!\n" |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 122 | # ... and read again using standard file methods |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 123 | mm.seek(0) |
| 124 | print(mm.readline()) # prints b"Hello world!\n" |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 125 | # close the map |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 126 | mm.close() |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 127 | |
| 128 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 129 | :class:`~mmap.mmap` can also be used as a context manager in a :keyword:`with` |
Julien Palard | 7855313 | 2018-03-28 23:14:15 +0200 | [diff] [blame] | 130 | statement:: |
Georg Brandl | 0bccc18 | 2010-08-01 14:50:00 +0000 | [diff] [blame] | 131 | |
| 132 | import mmap |
| 133 | |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 134 | with mmap.mmap(-1, 13) as mm: |
Zachary Ware | 42f740d | 2016-04-28 14:47:12 -0500 | [diff] [blame] | 135 | mm.write(b"Hello world!") |
Georg Brandl | 0bccc18 | 2010-08-01 14:50:00 +0000 | [diff] [blame] | 136 | |
| 137 | .. versionadded:: 3.2 |
| 138 | Context manager support. |
| 139 | |
| 140 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 141 | The next example demonstrates how to create an anonymous map and exchange |
| 142 | data between the parent and child processes:: |
| 143 | |
| 144 | import mmap |
| 145 | import os |
| 146 | |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 147 | mm = mmap.mmap(-1, 13) |
| 148 | mm.write(b"Hello world!") |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 149 | |
| 150 | pid = os.fork() |
| 151 | |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 152 | if pid == 0: # In a child process |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 153 | mm.seek(0) |
| 154 | print(mm.readline()) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 155 | |
Ezio Melotti | 6771462 | 2013-03-13 02:27:00 +0200 | [diff] [blame] | 156 | mm.close() |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 157 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 158 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 159 | Memory-mapped file objects support the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 161 | .. method:: close() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
Senthil Kumaran | b918395 | 2013-09-09 22:39:28 -0700 | [diff] [blame] | 163 | Closes the mmap. Subsequent calls to other methods of the object will |
| 164 | result in a ValueError exception being raised. This will not close |
| 165 | the open file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
| 167 | |
Georg Brandl | 0bccc18 | 2010-08-01 14:50:00 +0000 | [diff] [blame] | 168 | .. attribute:: closed |
| 169 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 170 | ``True`` if the file is closed. |
Georg Brandl | 0bccc18 | 2010-08-01 14:50:00 +0000 | [diff] [blame] | 171 | |
| 172 | .. versionadded:: 3.2 |
| 173 | |
| 174 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 175 | .. method:: find(sub[, start[, end]]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 176 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 177 | Returns the lowest index in the object where the subsequence *sub* is |
| 178 | found, such that *sub* is contained in the range [*start*, *end*]. |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 179 | Optional arguments *start* and *end* are interpreted as in slice notation. |
| 180 | Returns ``-1`` on failure. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 181 | |
Georg Brandl | 8c16cb9 | 2016-02-25 20:17:45 +0100 | [diff] [blame] | 182 | .. versionchanged:: 3.5 |
Serhiy Storchaka | 8490f5a | 2015-03-20 09:00:36 +0200 | [diff] [blame] | 183 | Writable :term:`bytes-like object` is now accepted. |
| 184 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 186 | .. method:: flush([offset[, size]]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 188 | Flushes changes made to the in-memory copy of a file back to disk. Without |
| 189 | use of this call there is no guarantee that changes are written back before |
| 190 | the object is destroyed. If *offset* and *size* are specified, only |
| 191 | changes to the given range of bytes will be flushed to disk; otherwise, the |
| 192 | whole extent of the mapping is flushed. |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 193 | |
Berker Peksag | e7d4b2f | 2018-08-22 21:21:05 +0300 | [diff] [blame] | 194 | ``None`` is returned to indicate success. An exception is raised when the |
| 195 | call failed. |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 196 | |
Berker Peksag | e7d4b2f | 2018-08-22 21:21:05 +0300 | [diff] [blame] | 197 | .. versionchanged:: 3.8 |
| 198 | Previously, a nonzero value was returned on success; zero was returned |
| 199 | on error under Windows. A zero value was returned on success; an |
| 200 | exception was raised on error under Unix. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | |
| 202 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 203 | .. method:: move(dest, src, count) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 205 | Copy the *count* bytes starting at offset *src* to the destination index |
| 206 | *dest*. If the mmap was created with :const:`ACCESS_READ`, then calls to |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 207 | move will raise a :exc:`TypeError` exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
| 209 | |
Charles-François Natali | 4dd453c | 2011-06-08 19:18:14 +0200 | [diff] [blame] | 210 | .. method:: read([n]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | |
Charles-François Natali | 4dd453c | 2011-06-08 19:18:14 +0200 | [diff] [blame] | 212 | Return a :class:`bytes` containing up to *n* bytes starting from the |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 213 | current file position. If the argument is omitted, ``None`` or negative, |
Charles-François Natali | 4dd453c | 2011-06-08 19:18:14 +0200 | [diff] [blame] | 214 | return all bytes from the current file position to the end of the |
| 215 | mapping. The file position is updated to point after the bytes that were |
| 216 | returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
Charles-François Natali | 4dd453c | 2011-06-08 19:18:14 +0200 | [diff] [blame] | 218 | .. versionchanged:: 3.3 |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 219 | Argument can be omitted or ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 221 | .. method:: read_byte() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 222 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 223 | Returns a byte at the current file position as an integer, and advances |
| 224 | the file position by 1. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | |
| 226 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 227 | .. method:: readline() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 229 | Returns a single line, starting at the current file position and up to the |
| 230 | next newline. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | |
| 232 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 233 | .. method:: resize(newsize) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 235 | Resizes the map and the underlying file, if any. If the mmap was created |
| 236 | with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 237 | raise a :exc:`TypeError` exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | |
| 239 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 240 | .. method:: rfind(sub[, start[, end]]) |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 241 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 242 | Returns the highest index in the object where the subsequence *sub* is |
| 243 | found, such that *sub* is contained in the range [*start*, *end*]. |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 244 | Optional arguments *start* and *end* are interpreted as in slice notation. |
| 245 | Returns ``-1`` on failure. |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 246 | |
Georg Brandl | 8c16cb9 | 2016-02-25 20:17:45 +0100 | [diff] [blame] | 247 | .. versionchanged:: 3.5 |
Serhiy Storchaka | 8490f5a | 2015-03-20 09:00:36 +0200 | [diff] [blame] | 248 | Writable :term:`bytes-like object` is now accepted. |
| 249 | |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 250 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 251 | .. method:: seek(pos[, whence]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 253 | Set the file's current position. *whence* argument is optional and |
| 254 | defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other |
| 255 | values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current |
| 256 | position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's end). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
| 258 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 259 | .. method:: size() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 261 | Return the length of the file, which can be larger than the size of the |
| 262 | memory-mapped area. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
| 264 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 265 | .. method:: tell() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 267 | Returns the current position of the file pointer. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | |
| 269 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 270 | .. method:: write(bytes) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
Benjamin Peterson | e099b37 | 2009-04-04 17:09:35 +0000 | [diff] [blame] | 272 | Write the bytes in *bytes* into memory at the current position of the |
Berker Peksag | 6282e65 | 2016-03-02 19:30:18 +0200 | [diff] [blame] | 273 | file pointer and return the number of bytes written (never less than |
| 274 | ``len(bytes)``, since if the write fails, a :exc:`ValueError` will be |
| 275 | raised). The file position is updated to point after the bytes that |
| 276 | were written. If the mmap was created with :const:`ACCESS_READ`, then |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 277 | writing to it will raise a :exc:`TypeError` exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | |
Georg Brandl | 8c16cb9 | 2016-02-25 20:17:45 +0100 | [diff] [blame] | 279 | .. versionchanged:: 3.5 |
Serhiy Storchaka | 8490f5a | 2015-03-20 09:00:36 +0200 | [diff] [blame] | 280 | Writable :term:`bytes-like object` is now accepted. |
| 281 | |
Berker Peksag | 6282e65 | 2016-03-02 19:30:18 +0200 | [diff] [blame] | 282 | .. versionchanged:: 3.6 |
| 283 | The number of bytes written is now returned. |
| 284 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 286 | .. method:: write_byte(byte) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
Ezio Melotti | e130a52 | 2011-10-19 10:58:56 +0300 | [diff] [blame] | 288 | Write the integer *byte* into memory at the current |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 289 | position of the file pointer; the file position is advanced by ``1``. If |
| 290 | the mmap was created with :const:`ACCESS_READ`, then writing to it will |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 291 | raise a :exc:`TypeError` exception. |