#include <stdlib.h>
#include <stdatomic.h>
#include <stddef.h>
#include <errno.h>
#include <time.h>
#include "config.h"
#include "os.h"
#include "refc.h"
#include "file.h"
#include "inode.h"

Data Structures
struct	ioctl_req
	Return/Request argument for FIOGETFD ioctl. More...
struct	tarfs_stats
struct	tarfs_fs
	This descriptor holds all file descriptors opened. More...
struct	statvfs
	The statvfs structure for systems without it (e.g. More...

Macros
#define	TARFS_MAX_FS CONFIG_TARFS_MAX_FS
#define	TARFS_MAX_FDS CONFIG_TARFS_MAX_FDS
#define	TARFS_IOCTL_BASE 0x54415200 /* "TAR\0" */
	ioctl() commands which are supported by this driver.
#define	FIOGETFD (TARFS_IOCTL_BASE + 0)
#define	FIONREAD (TARFS_IOCTL_BASE + 1)
#define	FIONBIO (TARFS_IOCTL_BASE + 2)
#define	log(Format_, ...)
#define	tarfs_logging(X_)

Enumerations
enum	{ ST_NOATIME = 1 , ST_NODEV = 2 , ST_NODIRATIME = 4 , ST_NOEXEC = 8 , ST_NOSUID = 16 , ST_RDONLY = 32 , ST_RELATIME = 64 , ST_SYNCHRONOUS = 128 }
	enum for statvfs More...

Functions
int	tarfs_mount (const char label, const char mountpoint, const char link_rebase, const char path_rebase)
	Mount a TARFS filesystem from an OS-specific resource.
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.
int	tarfs_unmount (const char *mountpoint)
	Unmount tar file system.
unsigned int	tarfs_fsck (const char *label)
	Perform a deep filesystem integrity check.
int	tarfs_integrity (int en)
	Enables or disables CRC64 integrity verification for TARFS archives.
int	tarfs_integrity_on_open (int fs_idx, int en)
	Enable, disable, or query per-open filesystem integrity checking.
int	tarfs_fsindex (const char *path)
	Find the filesystem responsible for a given path.
int	tarfs_info (const char mp, size_t raw_size, size_t *data_size)
	Get filesystem size information.
int	tarfs_statvfs (void ctx, struct statvfs st)
	Obtain filesystem statistics.
int	tarfs_dump (int fs_idx)
	Dump internal filesystem information for debugging.
int	tarfs_addref (struct tarfs_fs *fs)
	Filesystem reference counting.
int	tarfs_unref (struct tarfs_fs *fs)
struct tarfs_fs *	tarfs_getfs (int i)
	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.
struct tarfs_fs *	tarfs_getfs_addref (int i)
	Obtain raw pointer to the filesystem descriptor by filesystem slot Increment FS refcounter, used internally.
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)

Macro Definition Documentation

◆ FIOGETFD

#define FIOGETFD (TARFS_IOCTL_BASE + 0)

Convert global fd number to local fd number. arg=&int

Definition at line 47 of file fs.h.

Referenced by dupfd(), fdopendir(), mmap(), sendfile(), and tarf_ioctl().

◆ FIONBIO

#define FIONBIO (TARFS_IOCTL_BASE + 2)

Support FIONBIO (compatibility layer)

Definition at line 53 of file fs.h.

Referenced by tarf_ioctl().

◆ FIONREAD

#define FIONREAD (TARFS_IOCTL_BASE + 1)

Support FIONREAD (compatibility layer)

Definition at line 50 of file fs.h.

Referenced by tarf_ioctl().

◆ log

#define log	(		Format_,
			... )

Value:

do {} while(0)

Definition at line 445 of file fs.h.

Referenced by inode_alloc(), inode_lookup(), inode_mount(), inode_populate(), inode_resolve(), inode_unmount(), munmap(), tar_getnino(), tar_rootdir(), tard_closedir(), tard_fdopendir(), tard_opendir(), tard_readdir(), tard_seekdir(), tarf_close(), tarf_dupfd(), tarf_lseek(), tarf_mmap(), tarf_munmap(), tarf_open(), tarf_sendfile(), tarf_stat(), tarfs_getfs(), tarfs_getfs_addref(), tarfs_integrity(), tarfs_integrity_on_open(), tarfs_mount(), tarfs_mount_memory(), tarfs_os_map_tarfile(), and tarfs_unmount().

◆ TARFS_IOCTL_BASE

#define TARFS_IOCTL_BASE 0x54415200 /* "TAR\0" */

ioctl() commands which are supported by this driver.

Note: TARFS supports one special ioctl (FIOGETFD) to convert system-wide FD numbers to local fd numbers. This is required for POSIX mmap() implementation

Definition at line 44 of file fs.h.

◆ tarfs_logging

#define tarfs_logging ( X_ )

Value:

do {} while(0)

Definition at line 446 of file fs.h.

◆ TARFS_MAX_FDS

#define TARFS_MAX_FDS CONFIG_TARFS_MAX_FDS

Definition at line 30 of file fs.h.

◆ TARFS_MAX_FS

#define TARFS_MAX_FS CONFIG_TARFS_MAX_FS

Definition at line 29 of file fs.h.

Referenced by munmap(), tarf_munmap(), tarfs_fsindex(), tarfs_getfs(), and tarfs_getfs_addref().

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

enum for statvfs

Enumerator
ST_NOATIME
ST_NODEV
ST_NODIRATIME
ST_NOEXEC
ST_NOSUID
ST_RDONLY
ST_RELATIME
ST_SYNCHRONOUS

Definition at line 126 of file fs.h.

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 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().

Dump internal filesystem information for debugging.

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. 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"

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.

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.

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.

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.

< 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 )

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.

Lockless, not thread safe, does not increase refcounters.

Pointer returned by this function can not be stored

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

< 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 )

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

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)

< 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 filesystem size information.

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

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

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.

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.

Must be called before mount

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, or query per-open filesystem integrity checking.

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.

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

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 )

Mount a TARFS filesystem from an OS-specific resource.

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.

Mount a TARFS filesystem from an OS-specific resource.

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

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.

Parameters

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

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

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

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().

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ FIOGETFD

◆ FIONBIO

◆ FIONREAD

◆ log

◆ TARFS_IOCTL_BASE

◆ tarfs_logging

◆ TARFS_MAX_FDS

◆ TARFS_MAX_FS

Enumeration Type Documentation

◆ anonymous enum

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()