ra8_fs_fat_exfat_mutate.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"
 
/* ---- exFAT mutation helpers (unlink / rename / listdir) ------------------ */
 
/* `priv_exfat_bitmap_clear()`: see header for the documented contract. */
ra8_err_t
priv_exfat_bitmap_clear(const ra8_fs_mount_t* m, uint64_t bmp_lba, uint32_t clus, uint32_t count)
{
  uint64_t       loaded = UINT64_MAX;
  uint8_t* const sec    = priv_sec_io();
  for (uint32_t k = 0U; k < count; k++) {
    const uint32_t idx  = (clus - k_cluster_first_data) + k;
    const uint64_t lba  = bmp_lba + ((idx >> k_exfat_bit_shift) / priv_bps(m));
    const uint32_t byte = (idx >> k_exfat_bit_shift) % priv_bps(m);
    const uint32_t bit  = idx & k_exfat_bit_mask;
    ra8_err_t      e    = priv_exfat_bmp_switch(m, lba, &loaded, sec);
    if (e != k_ra8_ok) {
      return e;
    }
    sec[byte] = (uint8_t)(sec[byte] & (uint8_t)~(uint8_t)(1U << bit));
    /* Pull the scan hint back to the space just released, or the next create
     * would step over it and only find it after a full rescan (#607). */
    priv_alloc_hint_lower(m, idx + (uint32_t)k_cluster_first_data);
  }
  return priv_write_sector(m, loaded, sec);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_take_set(const ra8_fs_mount_t* m,
                                         exfat_cursor_t*       cur,
                                         const uint16_t*       name,
                                         uint32_t              nlen,
                                         uint32_t              sc,
                                         exfat_setpos_t*       pos,
                                         uint8_t*              strm_copy,
                                         uint8_t*              out_match)
{
  uint8_t matched = 1U;
  for (uint32_t k = 0U; k < sc; k++) {
    uint8_t         se[k_exfat_entry_bytes] = {};
    const ra8_err_t r                       = priv_exfat_next_entry(m, cur, se);
    if (r != k_ra8_ok) {
      return r;
    }
    /* AFTER the read: ::priv_exfat_next_entry may cross a cluster boundary before
     * reading, so the entry lives at the cursor's CURRENT cluster, one slot back
     * (it has already advanced past what it read). Capturing before the call
     * records (old cluster, one-past-end) for the first entry of a new cluster --
     * harmless while directories were one cluster, a mis-retired slot once they
     * grow (#677). */
    const exfat_setpos_t sp = {.cluster = cur->cluster, .index = cur->entry_in_cluster - 1U};
    pos[1U + k]             = sp;
    if (k == 0U) {
      if (se[0] != (uint8_t)k_exfat_entry_stream) {
        matched = 0U;
        continue;
      }
      if ((uint32_t)se[k_exfat_strm_off_nlen] != nlen) {
        matched = 0U;
        continue;
      }
      priv_byte_copy(strm_copy, se, (uint32_t)k_exfat_entry_bytes);
      continue;
    }
    if (matched == 0U) {
      continue;
    }
    if (se[0] != (uint8_t)k_exfat_entry_name) {
      matched = 0U;
      continue;
    }
    const uint32_t cpos = (k - 1U) * (uint32_t)k_exfat_name_per_entry;
    if (priv_exfat_name_chunk_eq(se, name, cpos, nlen) == 0U) {
      matched = 0U;
    }
  }
  *out_match = matched;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_try_set(const ra8_fs_mount_t* m,
                                        exfat_cursor_t*       cur,
                                        exfat_setpos_t        at,
                                        const uint8_t*        e,
                                        const uint16_t*       need,
                                        uint32_t              nlen,
                                        exfat_setpos_t*       pos,
                                        uint32_t              max_pos,
                                        uint32_t*             out_count,
                                        uint8_t*              file_copy,
                                        uint8_t*              strm_copy)
{
  const uint32_t sc    = (uint32_t)e[k_exfat_off_file_secnt];
  const uint32_t total = 1U + sc;
  if (total > max_pos) {
    return k_ra8_err_no_mem;
  }
  pos[0] = at;
  priv_byte_copy(file_copy, e, (uint32_t)k_exfat_entry_bytes);
  uint8_t         matched = 0U;
  const ra8_err_t r = internal_exfat_take_set(m, cur, need, nlen, sc, pos, strm_copy, &matched);
  if (r != k_ra8_ok) {
    return r;
  }
  if (matched == 1U) {
    *out_count = total;
    return k_ra8_ok;
  }
  return k_ra8_err_not_found;
}

ra8_err_t priv_exfat_find_set(const ra8_fs_mount_t* m,
                              const exfat_dir_t*    dir,
                              const char*           path,
                              exfat_setpos_t*       pos,
                              uint32_t              max_pos,
                              uint32_t*             out_count,
                              uint8_t*              file_copy,
                              uint8_t*              strm_copy)
{
  /* Strip leading slashes so a "/name" path matches (#93), as FAT does. */
  while (*path == '/') {
    path++;
  }
  uint16_t        need[k_exfat_name_cap] = {};
  uint32_t        nlen                   = 0U;
  const ra8_err_t ne = priv_exfat_needle_units(m, path, need, &nlen, k_ra8_err_not_found);
  if (ne != k_ra8_ok) {
    return ne;
  }
  exfat_cursor_t cur = {};
  priv_exfat_cursor_init(dir, &cur);
  while (cur.scanned < (uint32_t)k_exfat_scan_limit) {
    uint8_t   e[k_exfat_entry_bytes] = {};
    ra8_err_t r                      = priv_exfat_next_entry(m, &cur, e);
    if (r != k_ra8_ok) {
      return r;
    }
    /* AFTER the read (see ::priv_exfat_take_set): the File entry lives at the
     * cursor's current cluster, one slot back, so a set whose File entry is the
     * first of a grown cluster is recorded where it truly is (#677). */
    const exfat_setpos_t at = {.cluster = cur.cluster, .index = cur.entry_in_cluster - 1U};
    if (e[0] == (uint8_t)k_exfat_entry_eod) {
      return k_ra8_err_not_found;
    }
    if (e[0] != (uint8_t)k_exfat_entry_file) {
      continue;
    }
    r = internal_exfat_try_set(m,
                               &cur,
                               at,
                               e,
                               need,
                               nlen,
                               pos,
                               max_pos,
                               out_count,
                               file_copy,
                               strm_copy);
    if (r != k_ra8_err_not_found) {
      return r;
    }
  }
  return k_ra8_err_protocol_error;
}

RA8_INTERNAL
static ra8_err_t
internal_exfat_put_entry(const ra8_fs_mount_t* m, const exfat_setpos_t* where, const uint8_t* entry)
{
  return priv_exfat_write_dir_set(m,
                                  where->cluster,
                                  where->index,
                                  entry,
                                  (uint32_t)k_exfat_entry_bytes);
}

ra8_err_t priv_exfat_free_clusters(const ra8_fs_mount_t* m, const uint8_t* strm)
{
  const uint32_t first = priv_rd32(&strm[k_exfat_strm_off_clus]);
  /* The full 64-bit DataLength: reading only the low word here under-counted a
   * >4 GiB file's clusters and leaked the rest on unlink/truncate (#676). */
  const uint64_t size = priv_rd64(&strm[k_exfat_strm_off_dlen]);
  if (first < k_cluster_first_data) {
    return k_ra8_ok;
  }
  if (size == 0U) {
    return k_ra8_ok;
  }
  uint64_t  bmp_lba = 0U;
  ra8_err_t e       = priv_exfat_bitmap_lba(m, &bmp_lba);
  if (e != k_ra8_ok) {
    return e;
  }
  const uint32_t cluster_bytes = priv_cluster_bytes(m);
  const uint8_t  nofat =
    ((strm[k_exfat_strm_off_flags] & (uint8_t)k_exfat_secflag_no_fat) != 0U) ? 1U : 0U;
  if (nofat == 1U) {
    const uint32_t count = (uint32_t)((size + cluster_bytes - 1U) / cluster_bytes);
    return priv_exfat_bitmap_clear(m, bmp_lba, first, count);
  }
  uint32_t clus = first;
  for (uint32_t guard = 0U; guard < m->count_of_clusters; guard++) {
    e = priv_exfat_bitmap_clear(m, bmp_lba, clus, 1U);
    if (e != k_ra8_ok) {
      return e;
    }
    uint32_t next = 0U;
    e             = priv_fat_get(m, clus, &next);
    if (e != k_ra8_ok) {
      return e;
    }
    if (priv_is_eoc(m, next) != 0U) {
      return k_ra8_ok;
    }
    clus = next;
  }
  return k_ra8_err_protocol_error;
}
 
/* `priv_exfat_drop_set()`: see header for the documented contract. */
ra8_err_t priv_exfat_drop_set(const ra8_fs_mount_t* m, const exfat_setpos_t* pos, uint32_t count)
{
  for (uint32_t k = 0U; k < count; k++) {
    /* A single-entry read at a recorded position: contig_end is irrelevant
     * because this cursor never advances past the entry it was aimed at. */
    exfat_cursor_t one                        = {.cluster          = pos[k].cluster,
                                                 .entry_in_cluster = pos[k].index,
                                                 .scanned          = 0U,
                                                 .contig_end       = 0U};
    uint8_t        entry[k_exfat_entry_bytes] = {};
    ra8_err_t      e                          = priv_exfat_next_entry(m, &one, entry);
    if (e != k_ra8_ok) {
      return e;
    }
    entry[0] = (uint8_t)(entry[0] & (uint8_t)~(uint8_t)k_exfat_inuse_bit);
    e        = internal_exfat_put_entry(m, &pos[k], entry);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}
 
/* `priv_exfat_unlink_at()`: see header for the documented contract. */
ra8_err_t priv_exfat_unlink_at(const ra8_fs_mount_t* m, const exfat_dir_t* dir, const char* name)
{
  exfat_setpos_t  pos[k_exfat_set_max_entries] = {};
  uint32_t        count                        = 0U;
  uint8_t         file_e[k_exfat_entry_bytes]  = {};
  uint8_t         strm_e[k_exfat_entry_bytes]  = {};
  const ra8_err_t e = priv_exfat_find_set(m,
                                          dir,
                                          name,
                                          pos,
                                          (uint32_t)k_exfat_set_max_entries,
                                          &count,
                                          file_e,
                                          strm_e);
  if (e != k_ra8_ok) {
    return e;
  }
  /* A directory's entry set looks like a file's, so without this the chain
   * holding every child is handed to priv_exfat_free_clusters and the children
   * become unreachable allocated clusters -- silent, unrecoverable loss (#604). */
  if ((file_e[k_exfat_off_file_attr] & (uint8_t)k_exfat_attr_directory) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  /* Honor the read-only attribute (#681): a read-only file is refused before the
   * entry set is dropped or its clusters freed, so a denied unlink is a no-op. */
  if ((file_e[k_exfat_off_file_attr] & (uint8_t)k_exfat_attr_read_only) != 0U) {
    return k_ra8_err_access_denied;
  }
  const ra8_err_t de = priv_exfat_drop_set(m, pos, count);
  if (de != k_ra8_ok) {
    return de;
  }
  return priv_exfat_free_clusters(m, strm_e);
}
 
/* `priv_exfat_unlink()`: see header for the documented contract. */
ra8_err_t priv_exfat_unlink(const ra8_fs_mount_t* m, const char* path)
{
  exfat_dir_t     parent = {};
  const char*     leaf   = nullptr;
  const ra8_err_t e      = priv_exfat_resolve_parent(m, path, &parent, &leaf);
  if (e != k_ra8_ok) {
    return e;
  }
  if (priv_strlen(leaf) == 0U) {
    return k_ra8_err_invalid_arg; /* "/" names the root, which is not a file */
  }
  return priv_exfat_unlink_at(m, &parent, leaf);
}

RA8_INTERNAL
static uint32_t internal_exfat_build_rename_set(uint8_t*        set,
                                                const uint8_t*  file_e,
                                                const uint8_t*  strm_e,
                                                const uint16_t* new_name,
                                                uint32_t        new_len)
{
  const uint32_t name_entries =
    (new_len + (uint32_t)k_exfat_name_per_entry - 1U) / (uint32_t)k_exfat_name_per_entry;
  const uint32_t sec_count = 1U + name_entries;
  const uint32_t total     = (1U + sec_count) * (uint32_t)k_exfat_entry_bytes;
  for (uint32_t i = 0U; i < total; i++) {
    set[i] = 0U;
  }
  priv_byte_copy(&set[0], file_e, (uint32_t)k_exfat_entry_bytes);
  priv_byte_copy(&set[k_exfat_entry_bytes], strm_e, (uint32_t)k_exfat_entry_bytes);
  set[k_exfat_off_file_secnt] = (uint8_t)sec_count;
  uint8_t* strm               = &set[k_exfat_entry_bytes];
  strm[k_exfat_strm_off_nlen] = (uint8_t)new_len;
  priv_wr16(&strm[k_exfat_off_strm_hash], priv_exfat_name_hash(new_name, new_len));
  for (uint32_t n = 0U; n < name_entries; n++) {
    uint8_t* ne = &set[(size_t)(2U + n) * (size_t)k_exfat_entry_bytes];
    ne[0]       = (uint8_t)k_exfat_entry_name;
    for (uint32_t c = 0U; c < (uint32_t)k_exfat_name_per_entry; c++) {
      const uint32_t p = (n * (uint32_t)k_exfat_name_per_entry) + c;
      if (p < new_len) {
        priv_wr16(&ne[k_exfat_name_off + (c * 2U)], new_name[p]);
      }
    }
  }
  /* Access stamp only, and before the checksum that covers it. Same reasoning
   * as the FAT rename: the name moved, the bytes did not, so LastModified must
   * not move or every backup tool concludes the file changed (#601). */
  priv_exfat_file_stamp_access(set);
  priv_wr16(&set[k_exfat_off_file_csum], priv_exfat_set_checksum(set, total));
  return total;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_rename_prepare(const ra8_fs_mount_t* m,
                                               const char*           old_path,
                                               const char*           new_path,
                                               exfat_dir_t*          out_parent,
                                               const char**          out_old,
                                               const char**          out_new)
{
  exfat_dir_t     op = {};
  const char*     ol = nullptr;
  const ra8_err_t e1 = priv_exfat_resolve_parent(m, old_path, &op, &ol);
  if (e1 != k_ra8_ok) {
    return e1;
  }
  exfat_dir_t     np = {};
  const char*     nl = nullptr;
  const ra8_err_t e2 = priv_exfat_resolve_parent(m, new_path, &np, &nl);
  if (e2 != k_ra8_ok) {
    return e2;
  }
  if (op.cluster != np.cluster) {
    return k_ra8_err_not_supported;
  }
  if (priv_strlen(ol) == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if (priv_strlen(nl) == 0U) {
    return k_ra8_err_invalid_arg;
  }
  *out_parent = op;
  *out_old    = ol;
  *out_new    = nl;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_place_rename(const ra8_fs_mount_t* m,
                                             const exfat_dir_t*    parent,
                                             const exfat_setpos_t* pos,
                                             uint32_t              old_count,
                                             const uint8_t*        set,
                                             uint32_t              bytes)
{
  const uint32_t new_count = bytes / (uint32_t)k_exfat_entry_bytes;
  if (new_count == old_count) {
    for (uint32_t k = 0U; k < new_count; k++) {
      const ra8_err_t e =
        internal_exfat_put_entry(m, &pos[k], &set[(size_t)k * (size_t)k_exfat_entry_bytes]);
      if (e != k_ra8_ok) {
        return e;
      }
    }
    return k_ra8_ok;
  }
  uint32_t        nclus = 0U;
  uint32_t        nidx  = 0U;
  const ra8_err_t se    = priv_exfat_find_dir_space(m, parent, new_count, &nclus, &nidx);
  if (se != k_ra8_ok) {
    return se;
  }
  const ra8_err_t we = priv_exfat_write_dir_set(m, nclus, nidx, set, bytes);
  if (we != k_ra8_ok) {
    return we;
  }
  return priv_exfat_drop_set(m, pos, old_count);
}
 
/* `priv_exfat_rename()`: see header for the documented contract. */
ra8_err_t priv_exfat_rename(const ra8_fs_mount_t* m, const char* old_path, const char* new_path)
{
  exfat_dir_t     parent   = {};
  const char*     old_name = nullptr;
  const char*     new_name = nullptr;
  const ra8_err_t pe =
    internal_exfat_rename_prepare(m, old_path, new_path, &parent, &old_name, &new_name);
  if (pe != k_ra8_ok) {
    return pe;
  }
  /* The new leaf in UTF-16 up front: the built Name entries and the NameHash
   * both count CODE UNITS, and a UTF-8 argument of the same unit count can be
   * three times as many bytes (#606). A name over the cap is an argument fault,
   * not a full disk. The old leaf stays UTF-8: ::priv_exfat_find_set converts it
   * itself, and the entry count it reports is all the placement below needs. */
  uint16_t        new_units[k_exfat_name_cap] = {};
  uint32_t        new_len                     = 0U;
  const ra8_err_t nue =
    priv_exfat_needle_units(m, new_name, new_units, &new_len, k_ra8_err_invalid_arg);
  if (nue != k_ra8_ok) {
    return nue;
  }
  uint8_t e_strm[k_exfat_entry_bytes] = {};
  uint8_t e_attr                      = 0U;
  if (priv_exfat_find(m, &parent, new_name, e_strm, &e_attr) == k_ra8_ok) {
    return k_ra8_err_exists;
  }
  exfat_setpos_t  pos[k_exfat_set_max_entries] = {};
  uint32_t        count                        = 0U;
  uint8_t         file_e[k_exfat_entry_bytes]  = {};
  uint8_t         strm_e[k_exfat_entry_bytes]  = {};
  const ra8_err_t fe = priv_exfat_find_set(m,
                                           &parent,
                                           old_name,
                                           pos,
                                           (uint32_t)k_exfat_set_max_entries,
                                           &count,
                                           file_e,
                                           strm_e);
  if (fe != k_ra8_ok) {
    return fe;
  }
  /* Honor the read-only attribute (#681). file_e is the File entry read back by
   * priv_exfat_find_set above, so its FileAttributes low byte carries the
   * read-only bit; a read-only file is refused before the rename set is rebuilt
   * or placed. */
  if ((file_e[k_exfat_off_file_attr] & (uint8_t)k_exfat_attr_read_only) != 0U) {
    return k_ra8_err_access_denied;
  }
  uint8_t        set[k_exfat_max_set_bytes] = {};
  const uint32_t bytes = internal_exfat_build_rename_set(set, file_e, strm_e, new_units, new_len);
  return internal_exfat_place_rename(m, &parent, pos, count, set, bytes);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_gather_name(const ra8_fs_mount_t* m,
                                            exfat_cursor_t*       cur,
                                            uint32_t              sc,
                                            uint32_t              nlen,
                                            char*                 name,
                                            uint32_t              cap)
{
  uint16_t units[k_exfat_name_cap] = {};
  uint32_t got                     = 0U;
  name[0]                          = '\0';
  for (uint32_t k = 1U; k < sc; k++) {
    uint8_t         ne[k_exfat_entry_bytes] = {};
    const ra8_err_t r                       = priv_exfat_next_entry(m, cur, ne);
    if (r != k_ra8_ok) {
      return r;
    }
    if (ne[0] != (uint8_t)k_exfat_entry_name) {
      continue;
    }
    for (uint32_t c = 0U; c < (uint32_t)k_exfat_name_per_entry; c++) {
      const uint32_t p = ((k - 1U) * (uint32_t)k_exfat_name_per_entry) + c;
      if (p >= nlen) {
        break;
      }
      if (got < (uint32_t)k_exfat_name_cap) {
        units[got] = priv_rd16(&ne[k_exfat_name_off + (c * 2U)]);
        got++;
      }
    }
  }
  if (priv_utf16_to_utf8(units, got, name, cap) != k_ra8_ok) {
    name[0] = '\0';
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_list_emit(const ra8_fs_mount_t* m,
                                          exfat_cursor_t*       cur,
                                          const uint8_t*        e,
                                          ra8_fs_dirent_t*      out,
                                          bool*                 out_entry)
{
  const uint32_t sc                        = (uint32_t)e[k_exfat_off_file_secnt];
  const uint8_t  attr                      = e[k_exfat_off_file_attr];
  uint8_t        strm[k_exfat_entry_bytes] = {};
  ra8_err_t      r                         = priv_exfat_next_entry(m, cur, strm);
  if (r != k_ra8_ok) {
    return r;
  }
  if (strm[0] != (uint8_t)k_exfat_entry_stream) {
    return k_ra8_ok;
  }
  /* A directory's exFAT DataLength is its ALLOCATION, not a byte count, so
   * reporting it as a size would tell every caller that an empty folder held
   * a cluster's worth of bytes. FAT reports 0 for a directory and so does
   * ra8_fs_stat(); this is the third place that has to agree (#605). */
  uint64_t size = priv_rd64(&strm[k_exfat_strm_off_dlen]);
  if ((attr & (uint8_t)k_exfat_attr_directory) != 0U) {
    size = 0U;
  }
  const uint32_t nlen                      = (uint32_t)strm[k_exfat_strm_off_nlen];
  char           name[k_exfat_name_u8_cap] = {};
  r = internal_exfat_gather_name(m, cur, sc, nlen, name, (uint32_t)k_exfat_name_u8_cap);
  if (r != k_ra8_ok) {
    return r;
  }
  if (name[0] == '\0') {
    return k_ra8_ok; /* units no UTF-8 string encodes: report nothing, not a lie */
  }
  (void)memcpy(out->name, name, strlen(name) + 1U);
  out->attr       = attr;
  out->size_bytes = size;
  *out_entry      = true;
  return k_ra8_ok;
}
 
ra8_err_t priv_exfat_dir_next(const ra8_fs_mount_t* m,
                              exfat_cursor_t*       cur,
                              ra8_fs_dirent_t*      out,
                              bool*                 out_entry)
{
  *out_entry = false;
  while (cur->scanned < (uint32_t)k_exfat_scan_limit) {
    uint8_t   entry[k_exfat_entry_bytes] = {};
    ra8_err_t err                        = priv_exfat_next_entry(m, cur, entry);
    if (err == k_ra8_err_not_found) {
      return k_ra8_ok;
    }
    if (err != k_ra8_ok) {
      return err;
    }
    if (entry[0] == (uint8_t)k_exfat_entry_eod) {
      return k_ra8_ok;
    }
    if (entry[0] != (uint8_t)k_exfat_entry_file) {
      continue;
    }
    err = internal_exfat_list_emit(m, cur, entry, out, out_entry);
    if (err != k_ra8_ok) {
      return err;
    }
    if (*out_entry) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_invalid_size;
}
 
/* `priv_exfat_listdir()`: see header for the documented contract. */
ra8_err_t priv_exfat_listdir(const ra8_fs_mount_t* m,
                             const exfat_dir_t*    dir,
                             ra8_fs_listdir_cb_t   cb,
                             void*                 ctx)
{
  exfat_cursor_t cur = {};
  priv_exfat_cursor_init(dir, &cur);
  for (;;) {
    ra8_fs_dirent_t entry   = {};
    bool            present = false;
    const ra8_err_t err     = priv_exfat_dir_next(m, &cur, &entry, &present);
    if ((err != k_ra8_ok) || !present) {
      return err;
    }
    cb(entry.name, entry.attr, entry.size_bytes, ctx);
  }
}