:py:mod:`dissect.target.plugins.os.unix.locate.plocate`
=======================================================

.. py:module:: dissect.target.plugins.os.unix.locate.plocate


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.unix.locate.plocate.PLocateFile
   dissect.target.plugins.os.unix.locate.plocate.PLocatePlugin




Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.unix.locate.plocate.HAS_ZSTD
   dissect.target.plugins.os.unix.locate.plocate.plocate_def
   dissect.target.plugins.os.unix.locate.plocate.PLocateRecord
   dissect.target.plugins.os.unix.locate.plocate.c_plocate


.. py:data:: HAS_ZSTD
   :value: True

   

.. py:data:: plocate_def
   :value: Multiline-String

    .. raw:: html

        <details><summary>Show Value</summary>

    .. code-block:: python

        """
        #define MAGIC 0x00706c6f63617465             /* b'/x00plocate' */
        
        struct header {
            uint32_t version;
            uint32_t hashtable_size;
            uint32_t extra_ht_slots;
            uint32_t num_docids;
            uint64_t hash_table_offset_bytes;
            uint64_t filename_index_offset_bytes;
        
            /* Version 1 and up only. */
            uint32_t max_version;
            uint32_t zstd_dictionary_length_bytes;
            uint64_t zstd_dictionary_offset_bytes;
        
            /* Only if max_version >= 2, and only relevant for updatedb. */
            uint64_t directory_data_length_bytes;
            uint64_t directory_data_offset_bytes;
            uint64_t next_zstd_dictionary_length_bytes;
            uint64_t next_zstd_dictionary_offset_bytes;
            uint64_t conf_block_length_bytes;
            uint64_t conf_block_offset_bytes;
        
            uint8_t check_visibility;
            char padding[7];                         /* padding for alignment */
        };
        
        struct file {
            char path[];
        };
        """

    .. raw:: html

        </details>

   

.. py:data:: PLocateRecord

   

.. py:data:: c_plocate

   

.. py:class:: PLocateFile(fh: BinaryIO)


   plocate file parser

   The ``plocate.db`` file contains a hashtable and trigrams to enable quick lookups of filenames.

   We've implemented a few methods to gather those for possible future use, but for the PLocatePlugin
   we're only interested in the filepaths stored in the database. Hence we don't use these methods.

   Roughly speaking, the plocate.db file has the following structure:
       - ``header`` (0x70 bytes)
       - zstd compressed ``filename``s (until start of ``filename_index_offset_bytes``),
         possibly including a dictionary
       - hashtables (offset and length in ``header``)
       - directory data (offset and length in ``header``)
       - possible zstd dictionary (offset and length in ``header``)
       - configuration block (offset and length in ``header``)

   No documentation other than the source code is available on the format of this file.

   Resources:
       - https://git.sesse.net/?p=plocate

   .. py:attribute:: HEADER_SIZE
      :value: 112

      

   .. py:attribute:: NUM_OVERFLOW_SLOTS
      :value: 16

      

   .. py:attribute:: TRIGRAM_SIZE_BYTES
      :value: 16

      

   .. py:attribute:: DOCID_SIZE_BYTES
      :value: 8

      

   .. py:method:: __iter__() -> Iterable[PLocateFile]


   .. py:method:: filename_index() -> bytes

      Return the filename index of the plocate.db file.


   .. py:method:: hashtable() -> bytes

      Return the hashtable of the plocate.db file.



.. py:class:: PLocatePlugin(target: dissect.target.Target)


   Bases: :py:obj:`dissect.target.plugins.os.unix.locate.locate.BaseLocatePlugin`

   Base class for plugins.

   Plugins can optionally be namespaced by specifying the ``__namespace__``
   class attribute. Namespacing results in your plugin needing to be prefixed
   with this namespace when being called. For example, if your plugin has
   specified ``test`` as namespace and a function called ``example``, you must
   call your plugin with ``test.example``::

   A ``Plugin`` class has the following private class attributes:

   - ``__namespace__``
   - ``__record_descriptors__``

   With the following three being assigned in :func:`register`:

   - ``__plugin__``
   - ``__functions__``
   - ``__exports__``

   Additionally, the methods and attributes of :class:`Plugin` receive more private attributes
   by using decorators.

   The :func:`export` decorator adds the following private attributes

   - ``__exported__``
   - ``__output__``: Set with the :func:`export` decorator.
   - ``__record__``: Set with the :func:`export` decorator.

   The :func:`internal` decorator and :class:`InternalPlugin` set the ``__internal__`` attribute.
   Finally. :func:`args` decorator sets the ``__args__`` attribute.

   :param target: The :class:`~dissect.target.target.Target` object to load the plugin for.

   .. py:attribute:: __namespace__
      :value: 'plocate'

      

   .. py:attribute:: path
      :value: '/var/lib/plocate/plocate.db'

      

   .. py:method:: check_compatible() -> None

      Perform a compatibility check with the target.

      This function should return ``None`` if the plugin is compatible with
      the current target (``self.target``). For example, check if a certain
      file exists.
      Otherwise it should raise an ``UnsupportedPluginError``.

      :raises UnsupportedPluginError: If the plugin could not be loaded.


   .. py:method:: locate() -> PLocateRecord

      Yield file and directory names from the plocate.db.

      ``plocate`` is the default package on Ubuntu 22 and newer to locate files.
      It replaces ``mlocate`` and GNU ``locate``.

      Resources:
          - https://manpages.debian.org/testing/plocate/plocate.1.en.html
          - https://git.sesse.net/?p=plocate