file.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 file.h
 * @brief Public file API
 */
 
#pragma once

 
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <assert.h>
#include <sys/stat.h>
#include <sys/utime.h>
#include "config.h"
 
 
#ifdef __cplusplus
extern "C" {
#endif

struct tarfs_fp {
 
  uintptr_t fp_vaddr;  
  uint32_t  fp_pos;    
  size_t    fp_size;   
  int       fp_idx;    
};
 
 
/* VFS handlers below are normally invoked through a VFS.
 *
 * On systems without VFS support, applications should call the tarfs_(),
 * tarf_() and tard_() APIs directly. Unlike their POSIX counterparts, these
 * functions take an additional first argument: an index of the mounted
 * filesystem
 *
 * Typical usage without a VFS:
 *
 * 1. Mount the filesystem and save its identifier.
 *
 *      int ctx = tarfs_mount(...);
 *      if (ctx < 0)
 *          exit_error("failed to mount filesystem");
 *
 * 2. Use the context pointer in subsequent filesystem calls.
 *
 *      int fd1 = tarf_open((void *)ctx, "/home/file1.txt", flags);
 *      int fd2 = tarf_open((void *)ctx, "/home/file2.txt", flags);
 *      int fd3 = tarf_open((void *)ctx, "/home/file3.txt", flags);
 */
 
 

int tarf_access(void* ctx, const char *path, int amode);
 
 
/* close()
 * FS has at least 1 extra ref, because of open()
 *
 * close() is not thread-safe. It is not as bad as it seems: no crashes, no sigsegv.
 * Just DO NOT close() files being read() at the same time by another thread. Or, if you do, 
 * do not open another file immediately :)
 *
 * This is because of:
 *
 * Closing a file descriptor while another thread is executing read()
 * (or any operation using the same descriptor) is undefined behaviour.
 *
 * Since file descriptor slots are immediately reusable, a concurrent
 * open() may repurpose the same slot for another file before the running
 * operation completes, causing it to access the newly opened file instead
 * of the original one.
 *
 */
int tarf_close(void* ctx, int fd);

int tarf_open(void* ctx, const char * path, int flags, int mode);

ssize_t tarf_read(void* ctx, int fd, void *dst, size_t size);

ssize_t tarf_pread(void* ctx, int fd, void *dst, size_t size, off_t offset);

off_t tarf_lseek(void* ctx, int fd, off_t offset, int whence);

int tarf_fstat(void* ctx, int fd, struct stat * st);

int tarf_fsync(void* ctx, int fd);

int tarf_fcntl(void *ctx, int fd, int cmd, int arg);

int tarf_ioctl(void *ctx, int fd, int cmd, va_list args);

int tarf_stat(void* ctx, const char *path, struct stat *st);
 
 

int tarf_dupfd(void *ctx, int fd);

void *tarf_mmap(void *ctx, void *addr, size_t length, int prot, int flags, int fd, off_t offset);
 

int tarf_munmap(void *ctx, void *addr, size_t length);

ssize_t tarf_sendfile(void *ctx, int sock, int fd, off_t *offset, size_t count);
 
#ifdef __cplusplus
};
#endif
 
/* Compile-time sanity checks. */
_Static_assert(TARFS_MAX_FDS > 0 && TARFS_MAX_FDS <= 32, "Code review is required");