#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <stdbool.h>
#include <stdatomic.h>
#include <unistd.h>
#include <dirent.h>
#include <sys/errno.h>
#include <sys/fcntl.h>
#include "config.h"
#include "os.h"
#include "refc.h"
#include "fs.h"
#include "file.h"
#include "inode.h"

Functions
struct tarfs_fs *	tarfs_getfs (int i)
	Lockless, not thread safe, does not increase refcounters.
struct tarfs_fs *	tarfs_getfs_addref (int i)
	Thread safe, increases refcounter, uses mutex!
int	tarfs_fsindex (const char *path)
	Find the filesystem responsible for a given path.
int	tarfs_addref (struct tarfs_fs *fs)
	Filesystem reference counting.
int	tarfs_unref (struct tarfs_fs *fs)
int	tarfs_unmount (const char *mountpoint)
	Unmount tar file system.
int	tarfs_mount_memory (const void map, size_t size, const char mountpoint, const char link_rebase, const char path_rebase)
	Mount a TARFS filesystem from an already mapped memory buffer.
int	tarfs_mount (const char label, const char mountpoint, const char link_rebase, const char path_rebase)
	Actual mount procedure We expect sane label pointer (ASCIIZ) and a sane mountpoint (i.e.
void *	tarfs_calloc (size_t count, size_t size)
	calloc() based on a memory backend; Memory backend must set errno if there were errors
char *	tarfs_strdup (char const *str)
int	tarfs_info (const char mp, size_t raw_size, size_t *data_size)
	Get size information for TARFS.
unsigned int	tarfs_fsck (const char *label)
	Perform a deep filesystem integrity check.
int	tarfs_statvfs (void ctx, struct statvfs st)
	Obtain filesystem statistics.
int	tarfs_integrity_on_open (int fs_idx, int en)
	Enable/Disable/Get fs_opencrc flag for a filesystem with index fs_idx This flag enable optinal CRC64 checking on every open() call.
int	tarfs_integrity (int en)
	Enables or disables CRC64 integrity verification for TARFS archives.
int	tarfs_dump (int fs_idx)
	Dump FS statistics and content This functions is for debugging only and MUST NOT be used in production.

Function Documentation

◆ tarfs_addref()

int tarfs_addref ( struct tarfs_fs * fs )

Filesystem reference counting.

tarfs_addref() acquires a reference to the filesystem, while tarfs_unref() releases it. When the reference count reaches zero, the filesystem will be destroyed/unmounted.

Definition at line 253 of file fs.c.

References tarfs_fs::fs_ref.

Referenced by tarf_dupfd(), tarf_mmap(), and tarfs_getfs_addref().

◆ tarfs_calloc()

void * tarfs_calloc	(	size_t	count,
		size_t	size )

calloc() based on a memory backend; Memory backend must set errno if there were errors

Definition at line 492 of file fs.c.

References size, and tarfs_os_malloc().

Referenced by inode_alloc(), tard_fdopendir(), and tarfs_mount_memory().

◆ tarfs_dump()

int tarfs_dump ( int fs_idx )

Dump FS statistics and content This functions is for debugging only and MUST NOT be used in production.

Dump internal filesystem information for debugging.

Dump FS statistics and content This functions is for debugging only and MUST NOT be used in production.

Parameters

fs_idx Filesystem index returned by tarfs_mount().

Definition at line 832 of file fs.c.

References statvfs::f_badblocks, statvfs::f_badcrc, statvfs::f_blocks, statvfs::f_bmmap, statvfs::f_bread, statvfs::f_bsize, statvfs::f_dirs, statvfs::f_files, statvfs::f_frsize, statvfs::f_fsid, statvfs::f_links, statvfs::f_namemax, statvfs::f_nfail, statvfs::f_ram, and tarfs_statvfs().

◆ tarfs_fsck()

unsigned int tarfs_fsck ( const char * label )

Perform a deep filesystem integrity check.

Verifies the integrity of file contents if CRC64 checksums are present in the archive.

Parameters

label Filesystem label.

Returns: Number of entries that failed verification.

Verifies the integrity of file contents if CRC64 checksums are present in the archive. If there are no CRC64 sums then this function only checks headers

Parameters

label Filesystem label.

Returns: Number of entries that failed verification. If the actual TAR archive is smaller than size of a flash region where TAR file resides, then trailing garbage will be counted as "failed etries"

Definition at line 569 of file fs.c.

References size, tar_baddata(), tar_badhdr(), tar_octal(), tarfs_os_map_tarfile(), and tarfs_os_unmap_tarfile().

◆ tarfs_fsindex()

int tarfs_fsindex ( const char * path )

Find the filesystem responsible for a given path.

This function is NOT lockless and it is not fast: it does bruteforce strcmp over the list of mountpoints.

Returns: Filesystem slot index, or -1 if no mounted filesystem matches the specified path.

Searches all mounted filesystems and returns the filesystem whose mount point is the longest prefix of the supplied path. This allows nested mount points to work correctly. For example, if both /data and /data/logs are mounted, the path /data/logs/app.txt resolves to the latter.

A mount point matches only if it forms a complete path component. For example, /foo matches /foo and /foo/bar, but does not match /foobar.

Parameters

path	Absolute path to resolve.

Returns: Filesystem slot index, or -1 if no mounted filesystem matches the specified path.

< Max number of mounted TARFS filesystems

Definition at line 147 of file fs.c.

References TARFS_MAX_FS.

Referenced by statvfs(), and tarfs_info().

◆ tarfs_getfs()

struct tarfs_fs * tarfs_getfs ( int i )

Lockless, not thread safe, does not increase refcounters.

Obtain raw pointer to the filesystem descriptor by filesystem slot (value returned by tarfs_mount()) Used internally Platforms without VFS support will require user to pass FS descriptor manually to tarfs_read()/tarfs_open()/etc.

Must be only used when FS's refcounter is guaranteed > 1

Lockless, not thread safe, does not increase refcounters.

Pointer returned by this function can not be stored

< Max number of mounted TARFS filesystems

Definition at line 54 of file fs.c.

References log, and TARFS_MAX_FS.

Referenced by munmap(), tard_closedir(), tarf_munmap(), and tarfs_mount().

◆ tarfs_getfs_addref()

struct tarfs_fs * tarfs_getfs_addref ( int i )

Thread safe, increases refcounter, uses mutex!

Obtain raw pointer to the filesystem descriptor by filesystem slot Increment FS refcounter, used internally.

Must be used when filesystem #i is in unknown state (e.g. is being unmounted)

Thread safe, increases refcounter, uses mutex!

< Max number of mounted TARFS filesystems

Definition at line 70 of file fs.c.

References log, tarfs_addref(), and TARFS_MAX_FS.

Referenced by tard_fdopendir(), tarf_open(), tarfs_info(), tarfs_integrity_on_open(), and tarfs_statvfs().

◆ tarfs_info()

int tarfs_info	(	const char *	mp,
		size_t *	raw_size,
		size_t *	data_size )

Get size information for TARFS.

Get filesystem size information.

Parameters

	mp	mount point
[out]	raw_size	a pointer to a stored value. Can be NULL. TAR file size
[out]	data_size	a pointer to a stored value. Can be NULL. Real data (files)

Returns: 0 if success

Get size information for TARFS.

Parameters

	mp	Mount point
[out]	raw_size	Receives the total TAR archive size in bytes. May be NULL.
[out]	data_size	Receives the total size of all file data in bytes. May be NULL.

Returns: 0 if success, -1 otherwise

Note: This function may be used to check if FS is mounted by checking if tarfs_info(mountpoint, NULL, NULL) == 0

Definition at line 533 of file fs.c.

References tarfs_fs::fs_dsize, tarfs_fs::fs_size, tarfs_fsindex(), tarfs_getfs_addref(), and tarfs_unref().

◆ tarfs_integrity()

int tarfs_integrity ( int en )

Enables or disables CRC64 integrity verification for TARFS archives.

Must be called before mount

If the TARFS library is compiled with CONFIG_TARFS_INTEGRITY enabled, archives without a valid CRC64 checksum are treated as corrupted.

If a system uses both CRC64-protected and unprotected archives, CRC64 verification can be enabled or disabled as needed. This function must be called before tarfs_mount().

The setting is global and affects all subsequent calls to tarfs_mount().

Parameters

en	0 to disable CRC64 verification, 1 to enable it, or -1 to leave the current setting unchanged.

Returns: The previous CRC64 verification setting.

Definition at line 803 of file fs.c.

References log.

Referenced by inode_populate(), and tarfs_mount_memory().

◆ tarfs_integrity_on_open()

int tarfs_integrity_on_open	(	int	fs_idx,
		int	en )

Enable/Disable/Get fs_opencrc flag for a filesystem with index fs_idx This flag enable optinal CRC64 checking on every open() call.

Enable, disable, or query per-open filesystem integrity checking.

Parameters

fs_idx	A filesystem index as returned by the tarfs_mount() or by the tarfs_fsindex()
en	0 - diable, 1 - enable, -1 - do not change (to get current value see below)

Returns: previous value, before applying en

Enable/Disable/Get fs_opencrc flag for a filesystem with index fs_idx This flag enable optinal CRC64 checking on every open() call.

Enables or disables CRC64 integrity checking on every open() call for the filesystem identified by fs_idx. This provides additional protection against data corruption, but increases the time required to open a file.

By default, CRC64 integrity is checked when the filesystem is mounted. For systems with long uptimes, however, checking integrity only at mount time may not be sufficient.

Parameters

fs_idx	Filesystem index as returned by tarfs_mount() or tarfs_fsindex().
en	0 to disable checking, 1 to enable checking, or -1 to leave the current setting unchanged

Returns: The previous setting before applying en.

Definition at line 770 of file fs.c.

References tarfs_fs::fs_opencrc, log, tarfs_getfs_addref(), and tarfs_unref().

◆ tarfs_mount()

int tarfs_mount	(	const char *	label,
		const char *	mountpoint,
		const char *	link_rebase,
		const char *	path_rebase )

Actual mount procedure We expect sane label pointer (ASCIIZ) and a sane mountpoint (i.e.

Mount a TARFS filesystem from an OS-specific resource.

len>1, fisrt sym is /, last sym != /)

Actual mount procedure We expect sane label pointer (ASCIIZ) and a sane mountpoint (i.e.

The filesystem image is obtained using the OS abstraction layer function tarfs_os_map_tarfile(). The label parameter is passed to this function unchanged and is treated as an opaque identifier by TARFS.

Depending on the platform, label may represent a partition name, resource name, device identifier, or any other OS-specific object.

The mount point is normally obtained from the TARFS image metadata. It can be overridden explicitly by providing mountpoint.

Parameters

label	Opaque resource identifier passed to tarfs_os_map_tarfile().
mountpoint	Optional mount point override. If NULL, the mount point stored in the TARFS image is used.
link_rebase	Optional path prefix used to rebase symbolic links.

Returns: Filesystem slot index. The returned value can be passed to tarfs_getfs() to obtain the raw filesystem pointer.

Note: On platforms without a native VFS layer, the returned filesystem index can be used for direct TARFS access.

Definition at line 449 of file fs.c.

References tarfs_fs::fs_handle, log, size, tarfs_getfs(), tarfs_mount_memory(), tarfs_os_map_tarfile(), and tarfs_os_unmap_tarfile().

◆ tarfs_mount_memory()

int tarfs_mount_memory	(	const void *	addr,
		size_t	length,
		const char *	mountpoint,
		const char *	link_rebase,
		const char *	path_rebase )

Mount a TARFS filesystem from an already mapped memory buffer.

Unlike tarfs_mount(), this function does not use OS-specific resource mapping. The caller provides a pointer to an existing TAR image and its size directly.

This mode is suitable for TARFS images stored as linked firmware resources, embedded binary blobs, or any other memory region accessible by the application.

Note: TARFS does not copy the filesystem image. The supplied memory region must remain valid and unchanged while the filesystem is mounted.

Parameters

addr	Pointer to the beginning of the TAR image.
length	Size of the TAR image in bytes.
mountpoint	Mount point assigned to the filesystem.
link_rebase	Optional path prefix used to rebase symbolic links.
path_rebase	Optional override for a root dir. Will be stripped off every name. Normally autodetected, but autodetection MAY fail on damaged filesystem

Returns: Filesystem slot index. The returned value can be passed to tarfs_getfs() to obtain the raw filesystem pointer.

Definition at line 310 of file fs.c.

References tarfs_stats::badblocks, tarfs_stats::dirs, tarfs_stats::files, tarfs_fs::fs_dsize, tarfs_fs::fs_handle, tarfs_fs::fs_ino, tarfs_fs::fs_mountpoint, tarfs_fs::fs_ref, tarfs_fs::fs_size, tarfs_fs::fs_stats, tarfs_fs::fs_vaddr, inode_mount(), tarfs_stats::links, log, tarfs_stats::ram, size, tar_rootdir(), tarfs_calloc(), tarfs_integrity(), tarfs_os_free(), and tarfs_os_register_fs().

Referenced by tarfs_mount().

◆ tarfs_statvfs()

int tarfs_statvfs	(	void *	ctx,
		struct statvfs *	st )

Obtain filesystem statistics.

Fills a POSIX statvfs structure with information about the mounted filesystem. Since TARFS is a read-only filesystem, the number of available blocks and inodes is always reported as zero.

The struct statvfs is either provided by a platform (see src/config.h , CONFIG_TARFS_HAVE_STATVFS_H) or internal definition is used (struct statvfs is declared in src/fs.h). Latter provides additional fields which are not a part of the standart

Fills a POSIX statvfs structure with information about the mounted filesystem. Since TARFS is a read-only filesystem, the number of available blocks and inodes is always reported as zero.

Parameters

ctx	Filesystem context.
st	Pointer to the statvfs structure to fill.

Returns: 0 on success, or -1 on error with errno set appropriately.

Definition at line 686 of file fs.c.

References tarfs_stats::badblocks, tarfs_stats::dirs, statvfs::f_badblocks, statvfs::f_badcrc, statvfs::f_blocks, statvfs::f_bmmap, statvfs::f_bread, statvfs::f_bsize, statvfs::f_dirs, statvfs::f_files, statvfs::f_flag, statvfs::f_frsize, statvfs::f_fsid, statvfs::f_links, statvfs::f_namemax, statvfs::f_nfail, statvfs::f_ram, tarfs_stats::files, tarfs_fs::fs_bmmap, tarfs_fs::fs_bread, tarfs_fs::fs_dsize, tarfs_fs::fs_nfail, tarfs_fs::fs_stats, tarfs_stats::links, tarfs_stats::ram, ST_NOATIME, ST_NODEV, ST_NODIRATIME, ST_NOSUID, ST_RDONLY, tarfs_getfs_addref(), and tarfs_unref().

Referenced by statvfs(), and tarfs_dump().

◆ tarfs_strdup()

char * tarfs_strdup ( char const * str )

Definition at line 505 of file fs.c.

References tarfs_os_malloc().

Referenced by inode_populate().

◆ tarfs_unmount()

int tarfs_unmount ( const char * mountpoint )

Unmount tar file system.

Returns: 0 on success <0 FS is scheduled for unmount, but unmount is delayed because FS has some active users

Definition at line 267 of file fs.c.

References log, and tarfs_unref().

◆ tarfs_unref()

int tarfs_unref ( struct tarfs_fs * fs )

Definition at line 260 of file fs.c.

References tarfs_fs::fs_ref.

Referenced by tard_closedir(), tard_fdopendir(), tarf_close(), tarf_munmap(), tarf_open(), tarfs_info(), tarfs_integrity_on_open(), tarfs_statvfs(), and tarfs_unmount().

Functions

Function Documentation

◆ tarfs_addref()

◆ tarfs_calloc()

◆ tarfs_dump()

◆ tarfs_fsck()

◆ tarfs_fsindex()

◆ tarfs_getfs()

◆ tarfs_getfs_addref()

◆ tarfs_info()

◆ tarfs_integrity()

◆ tarfs_integrity_on_open()

◆ tarfs_mount()

◆ tarfs_mount_memory()

◆ tarfs_statvfs()

◆ tarfs_strdup()

◆ tarfs_unmount()

◆ tarfs_unref()