tar.h

Go to the documentation of this file.

/*
 * TARFS - Immutable (read-only) filesystem for embedded systems.
 *
 * Copyright (c) 2024-2026 Viacheslav Logunov
 * SPDX-License-Identifier: MMIT
 *
 * Author:
 *   Viacheslav Logunov <vvb333007@gmail.com>
 *
 * Project:
 *   https://github.com/vvb333007/tarfs
 *
 * @file tar.h
 * @brief Public tar file API 
 */
#pragma once 
 
#include "config.h"

typedef enum __attribute__((packed)) {
 
  TART_AFILE    = '\0',  
  TART_FILE     = '0',   
 
  TART_HARDLINK = '1',   
  TART_SYMLINK  = '2',   
  TART_DIR      = '5',   
 
  TART_PAX      = 'x',   
 
  // Ignored by TARFS
  TART_CHRDEV   = '3',   
  TART_BLKDEV   = '4',   
  TART_FIFO     = '6',   
  TART_CONT     = '7',   
  TART_PAX_G    = 'g',   
 
  /* Not a real type, used as a return value to indicate a bad type */
  TART_BAD       = 255,
 
} tart_t;

 
struct tarhdr {
 
  const char name[100];       
  const char mode[8];         
  const char uid[8];          
  const char gid[8];          
  const char size[12];        
  const char mtime[12];       
        char checksum[8];     
  const tart_t type;          
  const char link_name[100];  
  const char magic[6];        
  const char version[2];      
  const char user[32];        
  const char group[32];       
  const char major[8];        
  const char minor[8];        
  const char prefix[155];     
        char zero;              
#if CONFIG_TARFS_INTEGRITY
        char md[3];          
        char digest[8];      
#else
  const char pad[11];        
#endif                                  
 
} __attribute__((packed));
 
typedef struct tarhdr tarhdr_t;
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Checked TAR String   == "CTS", a byte sequence within a TAR archive terminated
 *                         by '\0', '\r', or '\n'.
 * Unchecked TAR String == "UTS", a byte sequence that may not be terminated.
 * C string             == a byte sequence terminated by '\0'.
 *
 * Strings stored in a TAR archive may or may not include a terminating
 * character. For this reason, TARFS provides a set of string helper
 * functions that mimic the behavior of the standard string.h functions.
 *
 * When operating on an Unchecked TAR String (UTS), the caller must provide
 * a pointer to the end of the string (e.g. tar_strcmp(), tar_strlen(), ...).
 */
 

int tar_strcmp(const char *s1, const char *s1_end, const char *s2);
 
/*
 * strncmp() for two CTS, len is the hard limit 
 *
 */
int tar_strncmp(const char *s1, const char *s2, size_t len);
 

int tar_strlen(const char *s1, const char *s1_end);

char *tar_strdup1(const char *s1, const char *s1_end);
 
/* Parse an octal number from a TAR field.
 *
 * Unlike strtol(), the input is not required to be NUL-terminated.
 * Parsing stops after max_len characters or at the first non-octal
 * character.
 *
 * @param p buffer start
 * @param max_len buffer length in bytes
 * @return decimal value
 */
uint32_t tar_octal(const char *p, size_t max_len);
 
#if CONFIG_TARFS_LOG
/* Devel only:
 * Displays CTS `buf`; `end` is the UTS_limit
 *
 * We dont go past the `end` pointer even if we didnt find any line 
 * terminator
 */
void tar_print(const char *buf, const char *end);
#endif /* CONFIG_TARFS_LOG */
 

bool tar_badhdr(tarhdr_t const * hdr);

int tar_getnino(const uint8_t *tar_start, size_t tar_length);
 

bool tar_rootdir(const uint8_t *tar_start, size_t tar_length, char *base_dir, size_t base_dir_len);
 
 
 
/* Calculate the checksum of a TAR header.
 *
 * While the checksum is being calculated, the checksum field itself
 * must be treated as eight ASCII space characters, as required by the
 * TAR format specification.
 *
 * The checksum field occupies bytes [148..156).
 *
 * @param hdr Pointer to the TAR header.
 * @return Header checksum.
 */
uint32_t tar_hdrsum(const tarhdr_t *hdr);
 

bool tar_baddata(struct tarhdr const *hdr, size_t size);
 
 
#ifdef TARSUM_BUILD
int tar_addsum(uint8_t *tar_start, size_t tar_length);
#endif /* TARSUM_BUILD */
 
      
#ifdef __cplusplus
};
#endif
 
_Static_assert(sizeof(tarhdr_t) == 512, "sizeof(tarhdr_t) != 512, code review is required");
_Static_assert(sizeof(tart_t) == 1, "sizeof(tar_type_t) != 1, code review is required");