Module Contents#



plocate file parser


Base class for plugins.


dissect.target.plugins.os.unix.locate.plocate.HAS_ZSTD = True#
dissect.target.plugins.os.unix.locate.plocate.plocate_def = Multiline-String#
Show Value
#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[];
class dissect.target.plugins.os.unix.locate.plocate.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.

__iter__() Iterable[PLocateFile]#
filename_index() bytes#

Return the filename index of the plocate.db file.

hashtable() bytes#

Return the hashtable of the plocate.db file.

class dissect.target.plugins.os.unix.locate.plocate.PLocatePlugin(target: dissect.target.Target)#

Bases: 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 register():

  • __plugin__

  • __functions__

  • __exports__

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

The export() decorator adds the following private attributes

  • __exported__

  • __output__: Set with the export() decorator.

  • __record__: Set with the export() decorator.

The internal() decorator and InternalPlugin set the __internal__ attribute. Finally. args() decorator sets the __args__ attribute.


target – The Target object to load the plugin for.

__namespace__ = 'plocate'#
path = '/var/lib/plocate/plocate.db'#
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.


UnsupportedPluginError – If the plugin could not be loaded.

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.