Skip to content

Latest commit

 

History

History
428 lines (311 loc) · 15.7 KB

mmap.rst

File metadata and controls

428 lines (311 loc) · 15.7 KB

:mod:`!mmap` --- Memory-mapped file support

.. module:: mmap
   :synopsis: Interface to memory-mapped files for Unix and Windows.

Memory-mapped file objects behave like both :class:`bytearray` and like :term:`file objects <file object>`. You can use mmap objects in most places where :class:`bytearray` are expected; for example, you can use the :mod:`re` module to search through a memory-mapped file. You can also change a single byte by doing obj[index] = 97, or change a subsequence by assigning to a slice: obj[i1:i2] = b'...'. You can also read and write data starting at the current file position, and :meth:`seek` through the file to different positions.

A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is different on Unix and on Windows. In either case you must provide a file descriptor for a file opened for update. If you wish to map an existing Python file object, use its :meth:`~io.IOBase.fileno` method to obtain the correct value for the fileno parameter. Otherwise, you can open the file using the :func:`os.open` function, which returns a file descriptor directly (the file still needs to be closed when done).

Note

If you want to create a memory-mapping for a writable, buffered file, you should :func:`~io.IOBase.flush` the file first. This is necessary to ensure that local modifications to the buffers are actually available to the mapping.

For both the Unix and Windows versions of the constructor, access may be specified as an optional keyword parameter. access accepts one of four values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to specify read-only, write-through or copy-on-write memory respectively, or :const:`ACCESS_DEFAULT` to defer to prot. access can be used on both Unix and Windows. If 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 :const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception. Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the underlying file. Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not update the underlying file.

.. versionchanged:: 3.7
   Added :const:`ACCESS_DEFAULT` constant.

To map anonymous memory, -1 should be passed as the fileno along with the length.

(Windows version) Maps length bytes from the file specified by the file handle fileno, and creates a mmap object. If length is larger than the current size of the file, the file is extended to contain length bytes. If length is 0, the maximum length of the map is the current size of the file, except that if the file is empty Windows raises an exception (you cannot create an empty mapping on Windows).

tagname, if specified and not 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 None, the mapping is created without a name. Avoiding the use of the tagname parameter will assist in keeping your code portable between Unix and Windows.

offset may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. offset defaults to 0. offset must be a multiple of the :const:`ALLOCATIONGRANULARITY`.

.. audit-event:: mmap.__new__ fileno,length,access,offset mmap.mmap

MADV_* Constants

.. data:: MADV_NORMAL
          MADV_RANDOM
          MADV_SEQUENTIAL
          MADV_WILLNEED
          MADV_DONTNEED
          MADV_REMOVE
          MADV_DONTFORK
          MADV_DOFORK
          MADV_HWPOISON
          MADV_MERGEABLE
          MADV_UNMERGEABLE
          MADV_SOFT_OFFLINE
          MADV_HUGEPAGE
          MADV_NOHUGEPAGE
          MADV_DONTDUMP
          MADV_DODUMP
          MADV_FREE
          MADV_NOSYNC
          MADV_AUTOSYNC
          MADV_NOCORE
          MADV_CORE
          MADV_PROTECT
          MADV_FREE_REUSABLE
          MADV_FREE_REUSE

   These options can be passed to :meth:`mmap.madvise`.  Not every option will
   be present on every system.

   Availability: Systems with the madvise() system call.

   .. versionadded:: 3.8

MAP_* Constants

.. data:: MAP_SHARED
          MAP_PRIVATE
          MAP_32BIT
          MAP_ALIGNED_SUPER
          MAP_ANON
          MAP_ANONYMOUS
          MAP_CONCEAL
          MAP_DENYWRITE
          MAP_EXECUTABLE
          MAP_HASSEMAPHORE
          MAP_JIT
          MAP_NOCACHE
          MAP_NOEXTEND
          MAP_NORESERVE
          MAP_POPULATE
          MAP_RESILIENT_CODESIGN
          MAP_RESILIENT_MEDIA
          MAP_STACK
          MAP_TPRO
          MAP_TRANSLATED_ALLOW_EXECUTE
          MAP_UNIX03

    These are the various flags that can be passed to :meth:`mmap.mmap`.  :data:`MAP_ALIGNED_SUPER`
    is only available at FreeBSD and :data:`MAP_CONCEAL` is only available at OpenBSD.  Note
    that some options might not be present on some systems.

    .. versionchanged:: 3.10
       Added :data:`MAP_POPULATE` constant.

    .. versionadded:: 3.11
       Added :data:`MAP_STACK` constant.

    .. versionadded:: 3.12
       Added :data:`MAP_ALIGNED_SUPER` and :data:`MAP_CONCEAL` constants.

    .. versionadded:: 3.13
       Added :data:`MAP_32BIT`, :data:`MAP_HASSEMAPHORE`, :data:`MAP_JIT`,
       :data:`MAP_NOCACHE`, :data:`MAP_NOEXTEND`, :data:`MAP_NORESERVE`,
       :data:`MAP_RESILIENT_CODESIGN`, :data:`MAP_RESILIENT_MEDIA`,
       :data:`MAP_TPRO`, :data:`MAP_TRANSLATED_ALLOW_EXECUTE`, and
       :data:`MAP_UNIX03` constants.