fs.h

Go to the documentation of this file.

/*
 * TARFS - Immutable (read-only) filesystem for embedded systems.
 *
 * Copyright (c) 2026 Viacheslav Logunov
 * SPDX-License-Identifier: MMIT
 *
 * Author:
 *   Viacheslav Logunov <vvb333007@gmail.com>
 *
 * Project:
 *   https://github.com/vvb333007/tarfs
 *
 * @file fs.h
 * @brief Public file system API
 */
 
 
#pragma once
 
#include <stdlib.h>
#include <stdatomic.h>
#include <stddef.h>
#include <errno.h>
#include <time.h>
 
#include "config.h"
#include "os.h"
 
#define TARFS_MAX_FS  CONFIG_TARFS_MAX_FS
#define TARFS_MAX_FDS CONFIG_TARFS_MAX_FDS
 
#include "refc.h"
#include "file.h"
#include "inode.h"
 

#define TARFS_IOCTL_BASE  0x54415200 /* "TAR\0" */
 
#ifndef FIOGETFD
#  define FIOGETFD (TARFS_IOCTL_BASE + 0)     
#endif
#ifndef FIONREAD
#  define FIONREAD (TARFS_IOCTL_BASE + 1)   
#endif
#ifndef FIONBIO
#  define FIONBIO (TARFS_IOCTL_BASE + 2)    
#endif

struct ioctl_req {
  int fs_idx; 
  int fd;     
};
 
/* Useful runtime stats on mounted filesystem. This one is required by statvfs() API
 * unlike counters, this structure is populated once at mount and never changed
 */
struct tarfs_stats {
 
  unsigned int badblocks; 
  unsigned int files;    
  unsigned int links;    
  unsigned int dirs;     
  unsigned int ram;      
#if CONFIG_TARFS_INTEGRITY
  unsigned int badcrc;   
#endif
};
 
#if CONFIG_TARFS_LOG
extern bool g_tarfs_log; 
#endif
 

struct tarfs_fs {
 
  refc_t                        fs_ref;               
  uintptr_t                     fs_handle;            
  void const                   *fs_vaddr;             
  size_t                        fs_dsize;             
  size_t                        fs_size;              
  uint32_t                      fs_nino;              
  tarfs_inode_t const * const * fs_ino;               
  tarfs_inode_t const *         fs_root;              
  _Atomic(uint32_t)             fs_usedfd;            
  struct tarfs_fp               fs_fd[TARFS_MAX_FDS]; 
  time_t                        fs_mtime;             
  uint16_t                      fs_opencrc:1;         
  uint16_t                      fs_reserved:15;       
  struct tarfs_stats            fs_stats;             
#if CONFIG_TARFS_COUNTERS                             
  uint64_t                      fs_bmmap;             
  uint64_t                      fs_bread;             
  uint32_t                      fs_nfail;             
#endif
  char                          fs_mountpoint[];      
};
 
 
#if CONFIG_TARFS_HAVE_STATVFS_H
#  include <sys/statvfs.h>
#else
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,
 
};

struct statvfs {
 
/* TODO: review types below. Right now it is a mess */
 
  size_t   f_bsize;    /* Filesystem block size */
  size_t   f_frsize;   /* Fragment size */
  size_t   f_blocks;   /* Size of fs in f_frsize units */
  size_t   f_bfree;    /* Number of free blocks */
  size_t   f_bavail;   /* Number of free blocks for unprivileged users */
  size_t   f_files;    /* Number of files */
  size_t   f_ffree;    /* Number of free inodes */
  size_t   f_favail;   /* Number of free inodes for unprivileged users */
  size_t   f_fsid;     /* Filesystem ID */
  int      f_flag;     /* Mount flags */
  size_t   f_namemax;  /* Maximum filename length */
 
/* TARFS extensions: */
 
  uint64_t f_bread;    /* Total bytes read()+pread() */
  uint64_t f_bmmap;    /* Total bytes mmap() */
  uint32_t f_nfail;    /* Total number of failures (e.g. out-of-memory, inode with NULL address etc) */
  size_t   f_badblocks; 
  size_t   f_links;     
  size_t   f_dirs;      
  size_t   f_ram;       
  size_t   f_badcrc;    
};
#endif
 
 
#ifdef __cplusplus
extern "C" {
#endif

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

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

unsigned int tarfs_fsck(const char *label);
 

int tarfs_integrity(int en);
 

 
int tarfs_integrity_on_open(int fs_idx, int en);

int tarfs_fsindex(const char *path);
 

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

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

int tarfs_dump(int fs_idx);
 
 
 
/******************************************************************
 * Internal API, not to be used by user program
 * 
 *******************************************************************/
 
 

int tarfs_addref(struct tarfs_fs *fs);
int tarfs_unref(struct tarfs_fs *fs);

struct tarfs_fs *tarfs_getfs(int i);

struct tarfs_fs *tarfs_getfs_addref(int i);
 
/* Implementation of a calloc() and a strdup() via memory backend
 *
 */
void *tarfs_calloc(size_t count, size_t size);
char *tarfs_strdup(char const *str);
static inline void tarfs_lock()   { tarfs_os_acquire_mutex(); }
static inline void tarfs_unlock() { tarfs_os_release_mutex(); }
static inline void tarfs_init()   { tarfs_os_init(); }
 
/* Logging, used internally by the tarfs library; Must be enabled in config.h (see CONFIG_TARFS_LOG macro)
 *
 * log() macro does all output (printf-like)
 * tarfs_logging() controls output of log() macro.
 *
 */
#if CONFIG_TARFS_LOG
 
#define log( Format_, ... ) do { if (g_tarfs_log) printf( "%s(): " Format_, __func__,  ##__VA_ARGS__ ); } while(0)
 
static inline void tarfs_logging(bool en) {
 
  g_tarfs_log = en;
  log("tarfs core logging enabled\r\n"); /* if it is disabled we don't see it */
 
}
#else
 
/* No-ops when logging is not compiled in 
 */
#define log( Format_, ... ) do {} while(0)
#define tarfs_logging( X_ ) do {} while(0)
 
#endif /* CONFIG_TARFS_LOG */
 
 
#ifdef __cplusplus
};
#endif