rest25/library/mmap.rst => rest262/library/mmap.rst
3==========================================
4
5.. module:: mmap
6   :synopsis: Interface to memory-mapped files for Unix and Windows.
7
8
9Memory-mapped file objects behave like both strings and like file objects.
10Unlike normal string objects, however, these are mutable.  You can use mmap
n11-objects in most places where strings are expected; for example, you can use the
n11+objects in most places where strings are expected; for example, you can use
12-:mod:`re` module to search through a memory-mapped file.  Since they're mutable,
12+the :mod:`re` module to search through a memory-mapped file.  Since they're
13-you can change a single character by doing ``obj[index] = 'a'``, or change a
13+mutable, you can change a single character by doing ``obj[index] = 'a'``, or
14-substring by assigning to a slice: ``obj[i1:i2] = '...'``.  You can also read
14+change a substring by assigning to a slice: ``obj[i1:i2] = '...'``.  You can
15-and write data starting at the current file position, and :meth:`seek` through
15+also read and write data starting at the current file position, and
16-the file to different positions.
16+:meth:`seek` through the file to different positions.
17
n18-A memory-mapped file is created by the :func:`mmap` function, which is different
n18+A memory-mapped file is created by the :class:`mmap` constructor, which is
19-on Unix and on Windows.  In either case you must provide a file descriptor for a
19+different on Unix and on Windows.  In either case you must provide a file
20-file opened for update. If you wish to map an existing Python file object, use
20+descriptor for a file opened for update. If you wish to map an existing Python
21-its :meth:`fileno` method to obtain the correct value for the *fileno*
21+file object, use its :meth:`fileno` method to obtain the correct value for the
22-parameter.  Otherwise, you can open the file using the :func:`os.open` function,
22+*fileno* parameter.  Otherwise, you can open the file using the
23-which returns a file descriptor directly (the file still needs to be closed when
23+:func:`os.open` function, which returns a file descriptor directly (the file
24-done).
24+still needs to be closed when done).
25
n26-For both the Unix and Windows versions of the function, *access* may be
n26+For both the Unix and Windows versions of the constructor, *access* may be
27specified as an optional keyword parameter. *access* accepts one of three
n28-values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to
n28+values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
29-specify readonly, write-through or copy-on-write memory respectively. *access*
29+to specify read-only, write-through or copy-on-write memory respectively.
30-can be used on both Unix and Windows.  If *access* is not specified, Windows
30+*access* can be used on both Unix and Windows.  If *access* is not specified,
31-mmap returns a write-through mapping.  The initial memory values for all three
31+Windows mmap returns a write-through mapping.  The initial memory values for
32-access types are taken from the specified file.  Assignment to an
32+all three access types are taken from the specified file.  Assignment to an
33-:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.  Assignment
33+:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
34-to an :const:`ACCESS_WRITE` memory map affects both memory and the underlying
34+Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the
35-file.  Assignment to an :const:`ACCESS_COPY` memory map affects memory but does
35+underlying file.  Assignment to an :const:`ACCESS_COPY` memory map affects
36-not update the underlying file.
36+memory but does 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
n42+.. versionchanged:: 2.6
43+   mmap.mmap has formerly been a factory function creating mmap objects. Now
44+   mmap.mmap is the class itself.
42
n43-.. function:: mmap(fileno, length[, tagname[, access]])
n46+.. class:: mmap(fileno, length[, tagname[, access[, offset]]])
44
n45-   **(Windows version)** Maps *length* bytes from the file specified by the file
n48+   **(Windows version)** Maps *length* bytes from the file specified by the
46-   handle *fileno*, and returns a mmap object.  If *length* is larger than the
49+   file handle *fileno*, and creates a mmap object.  If *length* is larger
47-   current size of the file, the file is extended to contain *length* bytes.  If
50+   than the current size of the file, the file is extended to contain *length*
48-   *length* is ``0``, the maximum length of the map is the current size of the
51+   bytes.  If *length* is ``0``, the maximum length of the map is the current
49-   file, except that if the file is empty Windows raises an exception (you cannot
52+   size of the file, except that if the file is empty Windows raises an
50-   create an empty mapping on Windows).
53+   exception (you cannot create an empty mapping on Windows).
51
n52-   *tagname*, if specified and not ``None``, is a string giving a tag name for the
n55+   *tagname*, if specified and not ``None``, is a string giving a tag name for
53-   mapping.  Windows allows you to have many different mappings against the same
56+   the mapping.  Windows allows you to have many different mappings against
54-   file.  If you specify the name of an existing tag, that tag is opened, otherwise
57+   the same file.  If you specify the name of an existing tag, that tag is
55-   a new tag of this name is created.  If this parameter is omitted or ``None``,
58+   opened, otherwise a new tag of this name is created.  If this parameter is
56-   the mapping is created without a name.  Avoiding the use of the tag parameter
59+   omitted or ``None``, the mapping is created without a name.  Avoiding the
57-   will assist in keeping your code portable between Unix and Windows.
60+   use of the tag parameter will assist in keeping your code portable between
61+   Unix and Windows.
58
n63+   *offset* may be specified as a non-negative integer offset. mmap references
64+   will be relative to the offset from the beginning of the file. *offset*
65+   defaults to 0.  *offset* must be a multiple of the ALLOCATIONGRANULARITY.
59
n67+ 
60-.. function:: mmap(fileno, length[, flags[, prot[, access]]])
68+.. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]])
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
n65-   maximum length of the map will be the current size of the file when :func:`mmap`
n73+   maximum length of the map will be the current size of the file when
66-   is called.
74+   :class:`mmap` is called.
67
68   *flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a
n69-   private copy-on-write mapping, so changes to the contents of the mmap object
n77+   private copy-on-write mapping, so changes to the contents of the mmap
70-   will be private to this process, and :const:`MAP_SHARED` creates a mapping
78+   object will be private to this process, and :const:`MAP_SHARED` creates a
71-   that's shared with all other processes mapping the same areas of the file.  The
79+   mapping that's shared with all other processes mapping the same areas of
72-   default value is :const:`MAP_SHARED`.
80+   the file.  The default value is :const:`MAP_SHARED`.
73
n74-   *prot*, if specified, gives the desired memory protection; the two most useful
n82+   *prot*, if specified, gives the desired memory protection; the two most
75-   values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify that the pages
83+   useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify
76-   may be read or written.  *prot* defaults to :const:`PROT_READ \| PROT_WRITE`.
84+   that the pages may be read or written.  *prot* defaults to
85+   :const:`PROT_READ \| PROT_WRITE`.
77
n78-   *access* may be specified in lieu of *flags* and *prot* as an optional keyword
n87+   *access* may be specified in lieu of *flags* and *prot* as an optional
79-   parameter.  It is an error to specify both *flags*, *prot* and *access*.  See
88+   keyword parameter.  It is an error to specify both *flags*, *prot* and
80-   the description of *access* above for information on how to use this parameter.
89+   *access*.  See the description of *access* above for information on how to
90+   use this parameter.
81
n92+   *offset* may be specified as a non-negative integer offset. mmap references
93+   will be relative to the offset from the beginning of the file. *offset*
94+   defaults to 0.  *offset* must be a multiple of the PAGESIZE or
95+   ALLOCATIONGRANULARITY.
96+ 
97+   This example shows a simple way of using :class:`mmap`::
98+ 
99+      import mmap
100+ 
101+      # write a simple example file
102+      with open("hello.txt", "w") as f:
103+          f.write("Hello Python!\n")
104+ 
105+      with open("hello.txt", "r+") as f:
106+          # memory-map the file, size 0 means whole file
107+          map = mmap.mmap(f.fileno(), 0)
108+          # read content via standard file methods
109+          print map.readline()  # prints "Hello Python!"
110+          # read content via slice notation
111+          print map[:5]  # prints "Hello"
112+          # update content using slice notation;
113+          # note that new content must have same size
114+          map[6:] = " world!\n"
115+          # ... and read again using standard file methods
116+          map.seek(0)
117+          print map.readline()  # prints "Hello  world!"
118+          # close the map
119+          map.close()
120+ 
121+ 
122+   The next example demonstrates how to create an anonymous map and exchange
123+   data between the parent and child processes::
124+ 
125+      import mmap
126+      import os
127+ 
128+      map = mmap.mmap(-1, 13)
129+      map.write("Hello world!")
130+ 
131+      pid = os.fork()
132+ 
133+      if pid == 0: # In a child process
134+          map.seek(0)
135+          print map.readline()
136+ 
137+          map.close()
138+ 
139+ 
82-Memory-mapped file objects support the following methods:
140+   Memory-mapped file objects support the following methods:
83
84
n85-.. method:: XXX Class.close()
n143+   .. method:: close()
86
n87-   Close the file.  Subsequent calls to other methods of the object will result in
n145+      Close the file.  Subsequent calls to other methods of the object will
88-   an exception being raised.
146+      result in an exception being raised.
89
90
n91-.. method:: XXX Class.find(string[, start])
n149+   .. method:: find(string[, start[, end]])
92
n93-   Returns the lowest index in the object where the substring *string* is found.
n151+      Returns the lowest index in the object where the substring *string* is
94-   Returns ``-1`` on failure.  *start* is the index at which the search begins, and
152+      found, such that *string* is contained in the range [*start*, *end*].
95-   defaults to zero.
153+      Optional arguments *start* and *end* are interpreted as in slice notation.
154+      Returns ``-1`` on failure.
96
97
n98-.. method:: XXX Class.flush([offset, size])
n157+   .. method:: flush([offset, size])
99
n100-   Flushes changes made to the in-memory copy of a file back to disk. Without use
n159+      Flushes changes made to the in-memory copy of a file back to disk. Without
101-   of this call there is no guarantee that changes are written back before the
160+      use of this call there is no guarantee that changes are written back before
102-   object is destroyed.  If *offset* and *size* are specified, only changes to the
161+      the object is destroyed.  If *offset* and *size* are specified, only
103-   given range of bytes will be flushed to disk; otherwise, the whole extent of the
162+      changes to the given range of bytes will be flushed to disk; otherwise, the
104-   mapping is flushed.
163+      whole extent of the mapping is flushed.
105
n165+      **(Windows version)** A nonzero value returned indicates success; zero
166+      indicates failure.
106
n168+      **(Unix version)** A zero value is returned to indicate success. An
169+      exception is raised when the call failed.
170+ 
171+ 
107-.. method:: XXX Class.move(dest, src, count)
172+   .. method:: move(dest, src, count)
108
n109-   Copy the *count* bytes starting at offset *src* to the destination index *dest*.
n174+      Copy the *count* bytes starting at offset *src* to the destination index
110-   If the mmap was created with :const:`ACCESS_READ`, then calls to move will throw
175+      *dest*.  If the mmap was created with :const:`ACCESS_READ`, then calls to
111-   a :exc:`TypeError` exception.
176+      move will throw a :exc:`TypeError` exception.
112
113
n114-.. method:: XXX Class.read(num)
n179+   .. method:: read(num)
115
n116-   Return a string containing up to *num* bytes starting from the current file
n181+      Return a string containing up to *num* bytes starting from the current
117-   position; the file position is updated to point after the bytes that were
182+      file position; the file position is updated to point after the bytes that
118-   returned.
183+      were returned.
119
120
n121-.. method:: XXX Class.read_byte()
n186+   .. method:: read_byte()
122
n123-   Returns a string of length 1 containing the character at the current file
n188+      Returns a string of length 1 containing the character at the current file
124-   position, and advances the file position by 1.
189+      position, and advances the file position by 1.
125
126
n127-.. method:: XXX Class.readline()
n192+   .. method:: readline()
128
n129-   Returns a single line, starting at the current file position and up to the next
n194+      Returns a single line, starting at the current file position and up to the
130-   newline.
195+      next newline.
131
132
n133-.. method:: XXX Class.resize(newsize)
n198+   .. method:: resize(newsize)
134
n135-   Resizes the map and the underlying file, if any. If the mmap was created with
n200+      Resizes the map and the underlying file, if any. If the mmap was created
136-   :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will throw a
201+      with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
137-   :exc:`TypeError` exception.
202+      throw a :exc:`TypeError` exception.
138
139
n205+   .. method:: rfind(string[, start[, end]])
206+ 
207+      Returns the highest index in the object where the substring *string* is
208+      found, such that *string* is contained in the range [*start*, *end*].
209+      Optional arguments *start* and *end* are interpreted as in slice notation.
210+      Returns ``-1`` on failure.
211+ 
212+ 
140-.. method:: XXX Class.seek(pos[, whence])
213+   .. method:: seek(pos[, whence])
141
n142-   Set the file's current position.  *whence* argument is optional and defaults to
n215+      Set the file's current position.  *whence* argument is optional and
143-   ``0`` (absolute file positioning); other values are ``1`` (seek relative to the
216+      defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other
217+      values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current
144-   current position) and ``2`` (seek relative to the file's end).
218+      position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
145
146
n147-.. method:: XXX Class.size()
n221+   .. method:: size()
148
n149-   Return the length of the file, which can be larger than the size of the memory-
n223+      Return the length of the file, which can be larger than the size of the
150-   mapped area.
224+      memory-mapped area.
151
152
n153-.. method:: XXX Class.tell()
n227+   .. method:: tell()
154
n155-   Returns the current position of the file pointer.
n229+      Returns the current position of the file pointer.
156
157
n158-.. method:: XXX Class.write(string)
n232+   .. method:: write(string)
159
n160-   Write the bytes in *string* into memory at the current position of the file
n234+      Write the bytes in *string* into memory at the current position of the
161-   pointer; the file position is updated to point after the bytes that were
235+      file pointer; the file position is updated to point after the bytes that
236+      were written. If the mmap was created with :const:`ACCESS_READ`, then
237+      writing to it will throw a :exc:`TypeError` exception.
238+ 
239+ 
240+   .. method:: write_byte(byte)
241+ 
242+      Write the single-character string *byte* into memory at the current
243+      position of the file pointer; the file position is advanced by ``1``. If
162-   written. If the mmap was created with :const:`ACCESS_READ`, then writing to it
244+      the mmap was created with :const:`ACCESS_READ`, then writing to it will
163-   will throw a :exc:`TypeError` exception.
245+      throw a :exc:`TypeError` exception.
164
165
t166-.. method:: XXX Class.write_byte(byte)
167- 
168-   Write the single-character string *byte* into memory at the current position of
169-   the file pointer; the file position is advanced by ``1``. If the mmap was
170-   created with :const:`ACCESS_READ`, then writing to it will throw a
171-   :exc:`TypeError` exception.
172- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op