:right-sidebar: True

MappedFile
===================================================================

.. currentmodule:: gi.repository.GLib





.. class:: MappedFile(**kwargs)
   :no-contents-entry:






The :obj:`~gi.repository.GLib.MappedFile` represents a file mapping created with
:func:`~gi.repository.GLib.MappedFile.new`. It has only private members and should
not be accessed directly.


Constructors
------------

.. rst-class:: interim-class

.. class:: MappedFile
   :no-index:


   .. classmethod:: new(filename: str, writable: bool) -> ~gi.repository.GLib.MappedFile

      Maps a file into memory. On UNIX, this is using the mmap() function.

      If ``writable`` is :const:`True`, the mapped buffer may be modified, otherwise
      it is an error to modify the mapped buffer. Modifications to the buffer
      are not visible to other processes mapping the same file, and are not
      written back to the file.

      Note that modifications of the underlying file might affect the contents
      of the :obj:`~gi.repository.GLib.MappedFile`\. Therefore, mapping should only be used if the file
      will not be modified, or if all modifications of the file are done
      atomically (e.g. using :func:`~gi.repository.GLib.file_set_contents`).

      If ``filename`` is the name of an empty, regular file, the function
      will successfully return an empty :obj:`~gi.repository.GLib.MappedFile`\. In other cases of
      size 0 (e.g. device files such as /dev/null), ``error`` will be set
      to the :obj:`~gi.repository.GLib.FileError` value :const:`~gi.repository.GLib.FileError.INVAL`.


      .. versionadded:: 2.8





      :param filename: The path of the file to load, in the GLib
             filename encoding

      :param writable: whether the mapping should be writable




   .. classmethod:: new_from_fd(fd: int, writable: bool) -> ~gi.repository.GLib.MappedFile

      Maps a file into memory. On UNIX, this is using the mmap() function.

      If ``writable`` is :const:`True`, the mapped buffer may be modified, otherwise
      it is an error to modify the mapped buffer. Modifications to the buffer
      are not visible to other processes mapping the same file, and are not
      written back to the file.

      Note that modifications of the underlying file might affect the contents
      of the :obj:`~gi.repository.GLib.MappedFile`\. Therefore, mapping should only be used if the file
      will not be modified, or if all modifications of the file are done
      atomically (e.g. using :func:`~gi.repository.GLib.file_set_contents`).


      .. versionadded:: 2.32





      :param fd: The file descriptor of the file to load

      :param writable: whether the mapping should be writable








Methods
-------

.. rst-class:: interim-class

.. class:: MappedFile
   :no-index:


   .. method:: free() -> None

      This call existed before :obj:`~gi.repository.GLib.MappedFile` had refcounting and is currently
      exactly the same as :func:`~gi.repository.GLib.MappedFile.unref`.


      .. versionadded:: 2.8




      .. deprecated:: 2.22

         Use :func:`~gi.repository.GLib.MappedFile.unref` instead.






   .. method:: get_bytes() -> ~gi.repository.GLib.Bytes

      Creates a new :obj:`~gi.repository.GLib.Bytes` which references the data mapped from ``file``\.
      The mapped contents of the file must not be modified after creating this
      bytes object, because a :obj:`~gi.repository.GLib.Bytes` should be immutable.


      .. versionadded:: 2.34








   .. method:: get_contents() -> str | None

      Returns the contents of a :obj:`~gi.repository.GLib.MappedFile`\.

      Note that the contents may not be zero-terminated,
      even if the :obj:`~gi.repository.GLib.MappedFile` is backed by a text file.

      If the file is empty then :const:`None` is returned.


      .. versionadded:: 2.8








   .. method:: get_length() -> int

      Returns the length of the contents of a :obj:`~gi.repository.GLib.MappedFile`\.


      .. versionadded:: 2.8