R_FS(3)

NAME
r_fs - radare2 filesystem library

SYNOPSIS
#include <r_fs.h>

DESCRIPTION
The r_fs library provides filesystem support for radare2, allowing analysis and manipulation of various filesystem types within binary images. It supports mounting, reading, writing, and navigating filesystems embedded in disk images or memory dumps.

Typical usage in the radare2 core allocates a filesystem context with RFS * fs via r_fs_new(void), and mounts a filesystem with r_fs_mount(RFS *fs, const char *fstype, const char *path, ut64 delta), so that commands in the core can list directories, open files and read their contents through the unified API. The core keeps a reference to the returned RFS context (see `libr/core/core.c`), and calls r_fs_free(RFS *fs) when tearing down.

The core structure is RFS, which manages plugins, mounted roots and binds I/O and console operations (see `libr/include/r_fs.h` for fields and types).

INITIALIZATION
RFS * r_fs_new(void)

Creates a new filesystem context with built-in plugins loaded.

void r_fs_free(RFS *fs)

Frees all resources associated with the filesystem context.

MOUNTING
RFSRoot * r_fs_mount(RFS *fs, const char *fstype, const char *path, ut64 delta)

Attachs a filesystem implementation (plugin) to a virtual mount point. The `delta` argument is commonly used when the filesystem is found at an offset inside a disk image or memory buffer. In the radare2 core this is typically invoked as:

    RFS *fs = r_fs_new();
    RFSRoot *root = r_fs_mount (fs, "auto", "/root", core->addr /* offset */);

bool r_fs_umount(RFS *fs, const char *path)

Unmounts the filesystem at the specified path.

FILE OPERATIONS
RFSFile * r_fs_open(RFS *fs, const char *path, bool create)

Open a file relative to mounted roots; when multiple roots match the path the first matching root is used. Callers in the core often do:

    RFSFile *f = r_fs_open (core->fs, "/some/path", false);
    if (f) {
        r_fs_read (core->fs, f, 0, f->size);
        r_fs_close (core->fs, f);
    }

void r_fs_close(RFS *fs, RFSFile *file)

Closes an open file handle.

int r_fs_read(RFS *fs, RFSFile *file, ut64 addr, int len)

Reads data from a file at the specified offset.

int r_fs_write(RFS *fs, RFSFile *file, ut64 addr, const ut8 *data, int len)

Writes data to a file at the specified offset.

DIRECTORY OPERATIONS
RList * r_fs_dir(RFS *fs, const char *path)

Returns a `RList` of `RFSFile` objects for the given virtual directory. The core uses this to implement the `md` command and directory listings; for example:

    RList *files = r_fs_dir (core->fs, "/");
    // iterate and inspect file->name, file->size, file->type

bool r_fs_dir_dump(RFS *fs, const char *path, const char *name)

Dumps the contents of a directory to disk.

FILE SLURPING
RFSFile * r_fs_slurp(RFS *fs, const char *path)

Convenience helper that opens and reads a file fully into memory returning an `RFSFile` whose `data` and `size` fields are populated. This is useful when a single buffer is required by consumers (e.g. analysis or dumping).

SEARCHING
RList * r_fs_find_name(RFS *fs, const char *name, const char *glob)

Finds files by name using glob patterns.

RList * r_fs_find_off(RFS *fs, const char *name, ut64 off)

Finds files containing data at a specific offset.

PARTITIONS
RList * r_fs_partitions(RFS *fs, const char *ptype, ut64 delta)

Enumerates partitions using the built-in partition detectors or a specific partition type. The returned list contains `RFSPartition` entries describing start and length; callers often use this to discover filesystems inside disk images before mounting them.

PLUGINS
bool r_fs_plugin_add(RFS *fs, RFSPlugin *p)

Adds a filesystem plugin to the context.

bool r_fs_plugin_remove(RFS *fs, RFSPlugin *p)

Removes a filesystem plugin from the context.

SHELL
bool r_fs_shell(RFSShell *shell, RFS *fs, const char *root)

Starts an interactive filesystem shell.

FILE TYPES
const RFSType * r_fs_type_index(int i)

Retrieves filesystem type information by index.

EXAMPLES
Common patterns used by the radare2 core and plugins:

    // create and mount a filesystem at a given offset
    RFS *fs = r_fs_new();
    RFSRoot *root = r_fs_mount (fs, "fat", "/mnt/fat", 0x1000);

    // open, read full contents and close
    RFSFile *file = r_fs_open (fs, "/README.txt", false);
    if (file) {
        r_fs_read (fs, file, 0, file->size);
        r_fs_close (fs, file);
    }

    // list a directory
    RList *files = r_fs_dir (fs, "/");

    // slurp a file into memory (single call)
    RFSFile *s = r_fs_slurp (fs, "/config.bin");
    if (s) {
        // use s->data and s->size
        r_fs_file_free (s);
    }

    // find files by name or containing an offset
    RList *matches = r_fs_find_name (fs, "/", "*.so");
    RList *byoff = r_fs_find_off (fs, "/", 0x2000);

SEE ALSO
r_io(3), r_core(3)